Senden von proaktiven Benachrichtigungen an BenutzerSend proactive notifications to users

gilt für: SDK v4APPLIES TO: SDK v4

In der Regel sendet ein Bot eine Nachricht direkt an einen Benutzer als Reaktion auf den Empfang einer Nachricht vom Benutzer.Typically, a bot sends a message to a user directly in response to receiving a message from the user. Gelegentlich muss ein Bot möglicherweise eine proaktive Nachricht senden, eine Nachricht als Reaktion auf eine Nachricht, die nicht vom Benutzer stammt.Occasionally, a bot might need to send a proactive message, a message in response to stimulus not originating from the user.

Proaktive Nachrichten können in einer Vielzahl von Szenarien nützlich sein.Proactive messages can be useful in a variety of scenarios. Wenn der Benutzer den Bot vorher aufgefordert hat, den Preis eines Produkts zu überwachen, kann der Bot den Benutzer warnen, wenn der Preis für das Produkt um 20 % gesunken ist.For example, if the user has previously asked the bot to monitor the price of a product, the bot can alert the user if the price of the product has dropped by 20%. Ein anderes Beispiel: Wenn ein Bot einen gewissen Zeitraum zum Kompilieren einer Antwort auf die Frage des Benutzers benötigt, kann er den Benutzer über die Verzögerung informieren und die Unterhaltung in der Zwischenzeit fortfahren lassen.Or, if a bot requires some time to compile a response to the user's question, it may inform the user of the delay and allow the conversation to continue in the meantime. Wenn der Bot die Kompilierung der Antwort auf die Frage abgeschlossen hat, teilt er dies dem Benutzer mit.When the bot finishes compiling the response to the question, it will share that information with the user.

Hinweis

In diesem Artikel werden informationen zu proaktiven Nachrichten für Bots im Allgemeinen behandelt.This article covers information about proactive messages for bots in general. Informationen zu proaktiven Nachrichten in Microsoft Teams finden Sie unter:For information about proactive messages in Microsoft Teams, see:

Requirements (Anforderungen)Requirements

Bevor Sie eine proaktive Nachricht senden können, benötigt Ihr Bot einen Konversationsverweis.Before you can send a proactive message, your bot needs a conversation reference. Ihr Bot kann den Konversationsverweis aus jeder Aktivität abrufen, die er vom Benutzer empfangen hat. Dies erfordert jedoch in der Regel, dass der Benutzer mindestens einmal mit dem Bot interagiert, bevor der Bot eine proaktive Nachricht senden kann.Your bot can retrieve the conversation reference from any activity it has received from the user, but this typically requires the user to interact with the bot at least once before the bot can send a proactive message.

Viele Kanäle hindern einen Bot am Messaging eines Benutzers, es sei denn, der Benutzer hat dem Bot mindestens einmal eine Nachricht angezeigt.Many channels prohibit a bot from messaging a user unless the user has messaged the bot at least once. Einige Kanäle lassen Ausnahmen zu.Some channels allow exceptions. Beispielsweise ermöglicht der Teams-Kanal Ihrem Bot, eine proaktive Nachricht (oder 1-on-1)-Nachricht an Personen in einer bereits eingerichteten Gruppenkonversation zu senden, die den Bot enthält.For instance, the Teams channel allows your bot to send a proactive (or 1-on-1) message to individuals in an already established group conversation that includes the bot.

VoraussetzungenPrerequisites

  • Sie müssen mit den Bot-Grundlagen vertraut sein.Understand bot basics.
  • Eine Kopie des Beispiels für proaktive Nachrichten in C#, JavaScript, Javaoder Python.A copy of the proactive messages sample in C#, JavaScript, Java, or Python. Anhand des Beispiels werden in diesem Artikel proaktive Nachrichten beschrieben.The sample is used to explain proactive messaging in this article.

Informationen zum Beispiel für proaktive NachrichtenAbout the proactive sample

Im Allgemeinen weist ein Bot als Anwendung einige Ebenen auf:In general, a bot as an application has a few layers:

  • Die Webanwendung, die HTTP-Anforderungen akzeptieren kann und speziell einen Messagingendpunkt unterstützt.The web application that can accept HTTP requests and specifically supports a messaging endpoint.
  • Ein Adapter, der die Konnektivität mit den Kanälen verarbeitet.An adapter that handles connectivity with the channels.
  • Ein Handler für den Turn, der in der Regel in einer Botklasse gekapselt ist, die die Konversationsursachen für die Bot-App verarbeitet.A handler for the turn, typically encapsulated in a bot class that handles the conversational reasoning for the bot app.

Als Reaktion auf eine eingehende Nachricht des Benutzers ruft die App die Prozessaktivitätsmethode des Adapters auf, die einen Turn- und Turn-Kontext erstellt, die Middlewarepipeline aufruft und dann den Turn-Handler des Bots aufruft.In response to an incoming message from the user, the app calls the adapter's process activity method, which creates a turn and turn context, calls its middleware pipeline, and then calls the bot's turn handler.

Um eine proaktive Nachricht zu initiieren, muss die Botanwendung zusätzliche Eingaben empfangen können.To initiate a proactive message, the bot application needs to be able to receive additional input. Die Anwendungslogik zum Initiieren einer proaktiven Nachricht liegt außerhalb des Bereichs des SDK.The application logic for initiating a proactive message is outside the scope of the SDK. In diesem Beispiel wird ein Endpunkt zur Benachrichtigung zusätzlich zu einem Standardnachrichtenendpunkt verwendet, um den proaktiven Turn auszulösen.For this sample, a notify endpoint, in addition to a standard messages endpoint, is used to trigger the proactive turn.

Als Reaktion auf eine GET-Anforderung an diesen Benachrichtigungsendpunkt ruft die App die Continue Conversation-Methode des Adapters auf, die sich ähnlich wie die Prozessaktivitätsmethode verhält.In response to a GET request on this notify endpoint, the app calls the adapter's continue conversation method, which behaves similarly to the the process activity method. Die Continue Conversation-Methode:The continue conversation method:

  • Verwendet einen geeigneten Konversationsverweis für den Benutzer und die Rückrufmethode, die für den proaktiven Turn verwendet werden soll.Takes an appropriate conversation reference for the user and the callback method to use for the proactive turn.
  • Erstellt eine Ereignisaktivität und einen Turn-Kontext für den proaktiven Turn.Creates an event activity and turn context for the proactive turn.
  • Ruft die Middlewarepipeline des Adapters auf.Calls the adapter's middleware pipeline.
  • Ruft die bereitgestellte Rückrufmethode auf.Calls the provided callback method.
  • Der Turn-Kontext verwendet den Konversationsverweis, um nachrichten an den Benutzer zu senden.The turn context uses the conversation reference to send any messages to the user.

Das Beispiel enthält einen Bot, einen Nachrichtenendpunkt und einen zusätzlichen Benachrichtigungsendpunkt, der zum Senden proaktiver Nachrichten an den Benutzer verwendet wird, wie in der folgenden Abbildung dargestellt.The sample has a bot, a messages endpoint, and an additional notify endpoint that is used to send proactive messages to the user, as shown in the following illustration.

Proaktiver Bot

Abrufen und Speichern des KonversationsverweisesRetrieve and store conversation reference

Wenn der Emulator eine Verbindung mit dem Bot herstellt, empfängt der Bot zwei Aktivitäten zur Konversationsaktualisierung.When the Emulator connects to the bot, the bot receives two conversation update activities. Im Aktivitätshandler des Bots für die Konversationsaktualisierung wird der Konversationsverweis abgerufen und in einem Wörterbuch gespeichert. Dies ist unten dargestellt.In the bot's conversation update activity handler, the conversation reference is retrieved and stored in a dictionary as shown below.

Bots\ProactiveBot.csBots\ProactiveBot.cs

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

Der Konversationsverweis enthält eine Konversationseigenschaft, die die Konversation beschreibt, in der die Aktivität vorhanden ist.The conversation reference includes a conversation property that describes the conversation in which the activity exists. Die Konversation enthält eine Benutzereigenschaft, die die an der Konversation beteiligten Benutzer auflistet, und eine Dienst-URL-Eigenschaft, die angibt, wohin Antworten auf die aktuelle Aktivität gesendet werden können.The conversation includes a user property that lists the users participating in the conversation, and a service URL property that indicates where replies to the current activity may be sent. Ein gültiger Konversationsverweis wird benötigt, um proaktive Nachrichten an Benutzer zu senden.A valid conversation reference is needed to send proactive messages to users. (Für den Teams-Kanal wird die Dienst-URL einem regionsisierten Server zugeordnet.)(For the Teams channel, the service URL maps to a regionalized server.)

Hinweis

In einem realen Szenario speichern Sie die Konversationsverweise in einer Datenbank, anstatt ein Objekt in einem Arbeitsspeicher zu verwenden.In a real-world scenario you would persist conversation references in a database instead of using an object in memory.

Senden der proaktiven NachrichtSend proactive message

Der zweite Controller, der Benachrichtigungscontroller, ist für das Senden der proaktiven Nachricht an den Benutzer verantwortlich.The second controller, the notify controller, is responsible for sending the proactive message to the user. Es werden die folgenden Schritte verwendet, um eine proaktive Nachricht zu generieren.It uses the following steps to generate a proactive message.

  1. Ruft den Verweis für die Konversation ab, an die die proaktive Nachricht gesendet werden soll.Retrieves the reference for the conversation to which to send the proactive message.
  2. Ruft die Continue Conversation-Methode des Adapters auf und stellt den Konversationsverweis und den zu verwendende Turn-Handlerdelegaten bereit.Calls the adapter's continue conversation method, providing the conversation reference and the turn handler delegate to use. (Die Continue Conversation-Methode generiert einen Turn-Kontext für die Konversation, auf die verwiesen wird, und ruft dann den angegebenen Turn-Handlerdelegaten auf.)(The continue conversation method generates a turn context for the referenced conversation and then calls the specified turn handler delegate.)
  3. Im Delegaten verwendet den Turn-Kontext, um die proaktive Nachricht zu senden.In the delegate, uses the turn context to send the proactive message. Hier wird der Delegat auf dem Benachrichtigungscontroller definiert und sendet die proaktive Nachricht an den Benutzer.Here, the delegate is defined on the notify controller, and it sends the proactive message to the user.

Hinweis

Während jeder Kanal eine stabile Dienst-URL verwenden sollte, kann sich die URL im Laufe der Zeit ändern.While each channel should use a stable service URL, the URL can change over time. Weitere Informationen zur Dienst-URL finden Sie in den Abschnitten Grundlegende Aktivitätsstruktur und Dienst-URL des Bot Framework-Aktivitätsschemas.For more information about the service URL, see the Basic activity structure and Service URL sections of the Bot Framework Activity Schema.

Wenn sich die Dienst-URL ändert, sind vorherige Konversationsverweise nicht mehr gültig, und Aufrufe zum Fortsetzen der Konversation generieren einen Fehler oder eine Ausnahme.If the service URL changes, previous conversation references will no longer be valid and calls to continue conversation will generate an error or exception. In diesem Fall muss Ihr Bot einen neuen Konversationsverweis für den Benutzer abrufen, bevor er proaktive Nachrichten erneut senden kann.In this case, your bot will need to acquire a new conversation reference for the user before it can send proactive messages again.

Controllers\NotifyController.csControllers\NotifyController .cs

Bei jeder Anforderung der notify-Seite des Bots ruft der notify-Controller die Konversationsverweise aus dem Wörterbuch ab.Each time the bot's notify page is requested, the notify controller retrieves the conversation references from the dictionary. Anschließend verwendet der Controller die Methoden ContinueConversationAsync und BotCallback, um die proaktive Nachricht zu senden.The controller then uses the ContinueConversationAsync and BotCallback methods to send the proactive message.

[Route("api/notify")]
[ApiController]
public class NotifyController : ControllerBase
{
    private readonly IBotFrameworkHttpAdapter _adapter;
    private readonly string _appId;
    private readonly ConcurrentDictionary<string, ConversationReference> _conversationReferences;

    public NotifyController(IBotFrameworkHttpAdapter adapter, IConfiguration configuration, ConcurrentDictionary<string, ConversationReference> conversationReferences)
    {
        _adapter = adapter;
        _conversationReferences = conversationReferences;
        _appId = configuration["MicrosoftAppId"] ?? string.Empty;
    }

    public async Task<IActionResult> Get()
    {
        foreach (var conversationReference in _conversationReferences.Values)
        {
            await ((BotAdapter)_adapter).ContinueConversationAsync(_appId, conversationReference, BotCallback, default(CancellationToken));
        }
        
        // Let the caller know proactive messages have been sent
        return new ContentResult()
        {
            Content = "<html><body><h1>Proactive messages have been sent.</h1></body></html>",
            ContentType = "text/html",
            StatusCode = (int)HttpStatusCode.OK,
        };
    }

    private async Task BotCallback(ITurnContext turnContext, CancellationToken cancellationToken)
    {
        await turnContext.SendActivityAsync("proactive hello");
    }
}

Zum Senden einer proaktiven Nachricht benötigt der Adapter eine App-ID für den Bot.To send a proactive message, the adapter requires an app ID for the bot. In einer Produktionsumgebung können Sie die App-ID des Bots verwenden.In a production environment, you can use the bot's app ID. Um den Bot lokal mit dem Emulator zu testen, können Sie die leere Zeichenfolge ("") verwenden.To test the bot locally with the Emulator, you can use the empty string ("").

Testen Ihres BotsTest your bot

  1. Installieren Sie Bot Framework Emulator (sofern noch nicht geschehen).If you have not done so already, install the Bot Framework Emulator.
  2. Führen Sie das Beispiel lokal auf Ihrem Computer aus.Run the sample locally on your machine.
  3. Starten Sie den Emulator, und stellen Sie eine Verbindung mit Ihrem Bot her.Start the Emulator and connect to your bot.
  4. Laden Sie die Seite „api/notify“ Ihres Bots.Load to your bot's api/notify page. Dadurch wird eine proaktive Nachricht im Emulator generiert.This will generate a proactive message in the Emulator.

Zusätzliche InformationenAdditional information

Neben dem in diesem Artikel verwendeten Beispiel sind weitere Beispiele auf GitHubverfügbar.Besides the sample used in this article, additional samples are available on GitHub.

Überlegungen zum EntwurfDesign considerations

Beim Implementieren von proaktiven Nachrichten in Ihrem Bot sollten Sie es vermeiden, innerhalb eines kurzen Zeitraums mehrere proaktive Nachrichten zu senden.When implementing proactive messages in your bot, don't send several proactive messages within a short amount of time. Einige Kanäle erzwingen Einschränkungen darüber, wie oft ein Bot Nachrichten an den Benutzer senden kann, und deaktivieren den Bot, wenn er gegen diese Einschränkungen verstößt.Some channels enforce restrictions on how frequently a bot can send messages to the user, and will disable the bot if it violates those restrictions.

Eine proaktive Ad-hoc-Nachricht ist der einfachste Typ von proaktiven Nachrichten.An ad hoc proactive message is the simplest type of proactive message. Der Bot streut die Nachricht einfach immer dann in die Konversation ein, wenn diese ausgelöst wird, ohne Rücksicht darauf, ob der Benutzer derzeit in einer anderen Konversation mit dem Bot aktiv ist und wird nicht versuchen, die Unterhaltung zu verändern.The bot simply interjects the message into the conversation whenever it is triggered, without any regard for whether the user is currently engaged in a separate topic of conversation with the bot and will not attempt to change the conversation in any way.

Ziehen Sie zur reibungsloseren Verarbeitung von Benachrichtigungen andere Möglichkeiten zum Integrieren der Benachrichtigung in den Konversationsablauf in Betracht. Legen Sie beispielsweise ein Flag im Konversationsstatus fest, oder fügen Sie die Benachrichtigung zu einer Warteschlange hinzu.To handle notifications more smoothly, consider other ways to integrate the notification into the conversation flow, such as setting a flag in the conversation state or adding the notification to a queue.

Informationen zum proaktiven TurnAbout the proactive turn

Die Continue Conversation-Methode verwendet den Konversationsverweis und einen Turn-Rückrufhandler für Folgendes:The continue conversation method uses the conversation reference and a turn callback handler to:

  1. Erstellen Sie einen Turn, in dem die Botanwendung die proaktive Nachricht senden kann.Create a turn in which the bot application can send the proactive message. Der Adapter erstellt eine event Aktivität für diesen Turn, wobei sein Name auf "ContinueConversation" festgelegt ist.The adapter creates an event activity for this turn, with its name set to "ContinueConversation".
  2. Senden Sie den Durchgang durch die Middlewarepipeline des Adapters.Send the turn through the adapter's middleware pipeline.
  3. Rufen Sie den Turn-Rückrufhandler auf, um benutzerdefinierte Logik auszuführen.Call the turn callback handler to perform custom logic.

Im Beispiel für proaktive Nachrichten wird der Turn-Rückrufhandler im Notify-Controller definiert und sendet die Nachricht direkt an die Konversation, ohne die proaktive Aktivität über den normalen Turn-Handler des Bots zu senden.In the proactive messages sample, the turn callback handler is defined in the notify controller and sends the message directly to the conversation, without sending the proactive activity through the bot's normal turn handler. Der Beispielcode greift auch beim proaktiven Turn nicht auf den Zustand des Bots zu oder aktualisiert den Zustand nicht.The sample code also does not access or update the bot's state on the proactive turn.

Viele Bots sind zustandsvoll und verwenden den Zustand, um eine Konversation über mehrere Turns zu verwalten.Many bots are stateful and use state to manage a conversation over multiple turns. Wenn die Continue Conversation-Methode einen Turn-Kontext erstellt, ist dem Turn der richtige Benutzer- und Konversationszustand zugeordnet, und Sie können proaktive Turns in die Logik Ihres Bots integrieren.When the continue conversation method creates a turn context, the turn will have the correct user and conversation state associated with it, and you can integrate proactive turns into your bot's logic. Wenn Sie die Botlogik benötigen, um die proaktive Nachricht zu kennen, haben Sie dazu einige Optionen.If you need the bot logic to be aware of the proactive message, you have a few options for doing so. Sie haben folgende Möglichkeiten:You can:

  • Geben Sie den Turn-Handler des Bots als Turn-Rückrufhandler an.Provide the bot's turn handler as the turn callback handler. Der Bot empfängt dann die Ereignisaktivität "ContinueConversation".The bot will then receive the "ContinueConversation" event activity.
  • Verwenden Sie den Turn-Rückrufhandler, um dem Turn-Kontext zuerst Informationen hinzuzufügen, und rufen Sie dann den Turn-Handler des Bots auf.Use the turn callback handler to add information to the turn context first, and then call the bot's turn handler.

In beiden Fällen müssen Sie Ihre Botlogik für die Behandlung des proaktiven Ereignisses entwerfen.In both of these cases, you will need to design your bot logic to handle the proactive event.

Nächste SchritteNext steps