Senden von proaktiven Benachrichtigungen an Benutzer

GILT FÜR: SDK v4

In der Regel sendet ein Bot eine Nachricht an einen Benutzer direkt als Antwort auf eine Nachricht des Benutzers. Gelegentlich kann es vorkommen, dass ein Bot eine proaktive Nachricht senden muss, d. h. eine Nachricht als Reaktion auf einen Anreiz, der nicht vom Benutzer ausgeht.

Proaktive Nachrichten können in verschiedenen Szenarien nützlich sein. 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. 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. Wenn der Bot die Kompilierung der Antwort auf die Frage abgeschlossen hat, teilt er dies dem Benutzer mit.

Dieser Artikel behandelt Informationen zu proaktiven Nachrichten für Bots im Allgemeinen. Informationen zu proaktiven Nachrichten in Microsoft Teams finden Sie unter

• DasBeispiel für Teams-Unterhaltungsbots in C#, JavaScript, Java oder Python.
• Die Microsoft-Teams-Dokumentation zum Senden proaktiver Nachrichten.

Hinweis

Die JavaScript-, C#- und Python-SDKs für Bot Framework werden weiterhin unterstützt, das Java-SDK wird jedoch eingestellt und der langfristige Support endet im November 2023.

Bestehende Bots, die mit dem Java SDK erstellt wurden, werden weiterhin funktionieren.

Für das erstellen eines neuen Bots sollten Sie Microsoft Copilot Studio verwenden und lesen, wie Sie die richtige Copilot-Lösung auswählen.

Weitere Informationen finden Sie unter Die Zukunft des Bot-Design.

Voraussetzungen

• Sie müssen mit den Bot-Grundlagen vertraut sein.
• Eine Kopie des Beispiels für proaktive Nachrichten in C#, JavaScript, Java oder Python. Anhand des Beispiels werden in diesem Artikel proaktive Nachrichten beschrieben.

Informationen zum Beispiel für proaktive Nachrichten

Im Allgemeinen verfügt ein Bot als Anwendung über einige Ebenen:

• Die Webanwendung, die HTTP-Anforderungen akzeptiert und speziell einen Messaging-Endpunkt unterstützt.
• Ein Adapter, der die Konnektivität mit den Kanälen verarbeitet.
• Ein Handler für den Durchlauf, in der Regel in einer Bot-Klasse gekapselt, die die Unterhaltungsüberlegungen für die Bot-App behandelt.

Als Antwort auf eine eingehende Nachricht des Benutzers ruft die App die Prozessaktivitätsmethode des Adapters auf, die einen Turn- und Turnkontext erstellt, die Middleware-Pipeline aufruft und dann den Turn-Handler des Bots aufruft.

Um eine proaktive Nachricht zu initiieren, muss die Botanwendung in der Lage sein, andere Eingaben zu empfangen. Die Anwendungslogik zum Initiieren einer proaktiven Nachricht liegt außerhalb des SDK-Bereichs. Für dieses Beispiel wird ein Benachrichtigungsendpunkt zusätzlich zu einem Standardnachrichtenendpunkt verwendet, um den proaktiven Turn auszulösen.

Als Reaktion auf eine GET-Anforderung für diesen Benachrichtigungsendpunkt ruft die App die Fortsetzungsunterhaltungs-Methode des Adapters auf, die sich ähnlich wie die Prozessaktivitäts-Methode verhält. Die Fortsetzungsunterhaltungs-Methode:

• Verwendet eine geeignete Unterhaltungsreferenz für den Benutzer und die Rückrufmethode, die für den proaktiven Turn verwendet werden soll.
• Erstellt eine Ereignisaktivität und einen Turn-Kontext für den proaktiven Turn.
• Ruft die Middleware-Pipeline des Adapters auf.
• Ruft die bereitgestellte Rückrufmethode auf.
• Der Turnkontext verwendet die Unterhaltungsreferenz, um Nachrichten an den Benutzer zu senden.

Das Beispiel hat einen Bot, einen Nachrichten-Endpunkt und einen zusätzlichen Endpunkt, der zum Senden von proaktiven Nachrichten an den Benutzer verwendet wird, wie in der folgenden Abbildung gezeigt.

Abrufen und Speichern des Konversationsverweises

Wenn der Bot Framework Emulator eine Verbindung mit dem Bot herstellt, empfängt der Bot zwei Aktivitäten zur Konversationsaktualisierung. Im Aktivitätshandler des Bots für die Konversationsaktualisierung wird der Konversationsverweis abgerufen und in einem Wörterbuch gespeichert. Dies ist unten dargestellt.

C#

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

JavaScript

bots/proactiveBot.js

this.onConversationUpdate(async (context, next) => {
    this.addConversationReference(context.activity);

    await next();
});

addConversationReference(activity) {
    const conversationReference = TurnContext.getConversationReference(activity);
    this.conversationReferences[conversationReference.conversation.id] = conversationReference;
}

Java

ProactiveBot.java

@Override
protected CompletableFuture<Void> onConversationUpdateActivity(TurnContext turnContext) {
    addConversationReference(turnContext.getActivity());
    return super.onConversationUpdateActivity(turnContext);
}

// adds a ConversationReference to the shared Map.
private void addConversationReference(Activity activity) {
    ConversationReference conversationReference = activity.getConversationReference();
    conversationReferences.put(conversationReference.getUser().getId(), conversationReference);
}

Python

bots/proactive_bot.py

async def on_conversation_update_activity(self, turn_context: TurnContext):
    self._add_conversation_reference(turn_context.activity)
    return await super().on_conversation_update_activity(turn_context)

def _add_conversation_reference(self, activity: Activity):
    """
    This populates the shared Dictionary that holds conversation references. In this sample,
    this dictionary is used to send a message to members when /api/notify is hit.
    :param activity:
    :return:
    """
    conversation_reference = TurnContext.get_conversation_reference(activity)
    self.conversation_references[
        conversation_reference.user.id
    ] = conversation_reference

Der Konversationsverweis beinhaltet eine conversation-Eigenschaft, mit der die Konversation beschrieben wird, in der die Aktivität enthalten ist. Die Konversation beinhaltet eine user-Eigenschaft, mit der die Benutzer aufgeführt werden, die an der Konversation teilnehmen. Außerdem ist eine service URL-Eigenschaft vorhanden, die angibt, wohin Antworten auf die aktuelle Aktivität gesendet werden können. Ein gültiger Konversationsverweis wird benötigt, um proaktive Nachrichten an Benutzer zu senden. (Für den Teams-Kanal wird die Dienst-URL einem regionalisierten Server zugeordnet.)

Hinweis

In einem realen Szenario speichern Sie die Konversationsverweise in einer Datenbank, anstatt ein Objekt in einem Arbeitsspeicher zu verwenden.

Proaktive Nachricht senden

Der zweite Controller (notify) ist für das Senden der proaktiven Nachricht an den Benutzer zuständig. Er führt die folgenden Schritte aus, um eine proaktive Nachricht zu generieren.

1. Ruft den Verweis für die Konversation ab, an die die proaktive Nachricht gesendet werden soll.
2. Ruft die continue conversation-Methode des Adapters auf, und geben Sie den Konversationsverweis und den gewünschten Turn-Handler-Delegaten an. (Mit der „continue conversation“-Methode wird ein Turn-Kontext für die referenzierte Konversation generiert und anschließend der angegebene Turn-Handler-Delegat aufgerufen.)
3. Verwenden Sie im Delegaten den Turn-Kontext, um die proaktive Nachricht zu senden. Hier ist der Delegat auf dem Benachrichtigungscontroller definiert und sendet die proaktive Nachricht an den Benutzer.

Hinweis

Während jeder Kanal eine stabile Dienst-URL verwenden sollte, kann sich die URL im Laufe der Zeit ändern. Weitere Informationen zur Dienst-URL finden Sie in den Abschnitten Grundlegende Aktivitätsstruktur und Dienst-URL des Bot-Framework-Aktivitätsschemas.

Wenn sich die Dienst-URL ändert, sind frühere Unterhaltungsverweise nicht mehr gültig und Anrufe zum Fortsetzen der Unterhaltung generieren einen Fehler oder eine Ausnahme. In diesem Fall muss Ihr Bot einen neuen Unterhaltungsverweis für den Benutzer erwerben, bevor er proaktive Nachrichten erneut senden kann.

C#

Controllers\NotifyController.cs

Bei jeder Anforderung der notify-Seite des Bots ruft der notify-Controller die Konversationsverweise aus dem Wörterbuch ab. Anschließend verwendet der Controller die Methoden ContinueConversationAsync und BotCallback, um die proaktive Nachricht zu senden.

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

JavaScript

index.js

Bei jeder Anforderung der /api/notify-Seite des Servers ruft der Server die Konversationsverweise aus dem Wörterbuch ab. Der Server verwendet dann die continueConversation-Methode, um die proaktive Nachricht zu senden. Der Parameter für continueConversation ist eine Funktion, die für diesen Turn als Turn-Handler des Bots dient.

    res.setHeader('Content-Type', 'text/html');
    res.writeHead(200);
    res.write('<html><body><h1>Proactive messages have been sent.</h1></body></html>');
    res.end();
});

Java

NotifyController.java

Bei jeder Anforderung der notify-Seite des Bots ruft der notify-Controller die Konversationsverweise aus dem Wörterbuch ab. Anschließend verwendet der Controller die Methoden continueConversation, um die proaktive Nachricht zu senden.

@RestController
public class NotifyController {
    /**
     * The BotFrameworkHttpAdapter to use. Note is is provided by dependency
     * injection via the constructor.
     *
     * @see com.microsoft.bot.integration.spring.BotDependencyConfiguration
     */
    private final BotFrameworkHttpAdapter adapter;

    private ConversationReferences conversationReferences;
    private String appId;

    @Autowired
    public NotifyController(
        BotFrameworkHttpAdapter withAdapter,
        Configuration withConfiguration,
        ConversationReferences withReferences
    ) {
        adapter = withAdapter;
        conversationReferences = withReferences;
        appId = withConfiguration.getProperty("MicrosoftAppId");
    }

    @GetMapping("/api/notify")
    public ResponseEntity<Object> proactiveMessage() {
        for (ConversationReference reference : conversationReferences.values()) {
            adapter.continueConversation(
                appId, reference, turnContext -> turnContext.sendActivity("proactive hello").thenApply(resourceResponse -> null)
            );
        }

        // Let the caller know proactive messages have been sent
        return new ResponseEntity<>(
            "<html><body><h1>Proactive messages have been sent.</h1></body></html>",
            HttpStatus.ACCEPTED
        );
    }
}

Python

Bei jeder Anforderung der Benachrichtigungsseite des Bots ruft der Server die Konversationsverweise aus dem Wörterbuch ab. Der Server verwendet dann die _send_proactive_message, um die proaktive Nachricht zu senden.

if __name__ == "__main__":
    try:
        web.run_app(APP, host="localhost", port=CONFIG.PORT)
    except Exception as error:
        raise error

Zum Senden einer proaktiven Nachricht benötigt der Adapter eine App-ID für den Bot. In einer Produktionsumgebung können Sie die App-ID des Bots verwenden. Um den Bot lokal mit dem Emulator zu testen, können Sie die leere Zeichenfolge ("") verwenden.

Bot testen

1. Installieren Sie Bot Framework Emulator, sofern noch nicht geschehen.
2. Führen Sie das Beispiel lokal auf Ihrem Computer aus.
3. Starten des Emulators und Herstellen einer Verbindung mit Ihrem Bot.
4. Laden Sie die Seite „api/notify“ Ihres Bots. Im Emulator wird daraufhin eine proaktive Nachricht generiert.

Weitere Informationen

Anforderungen

Bevor Sie eine proaktive Nachricht senden können, benötigt Ihr Bot einen Unterhaltungsverweis. Ihr Bot kann den Unterhaltungsverweis von jeder Aktivität abrufen, die er vom Benutzer erhalten hat. Dies erfordert jedoch in der Regel, dass der Benutzer mindestens einmal mit dem Bot interagiert, bevor der Bot eine proaktive Nachricht senden kann.

Viele Kanäle verbieten einem Bot, einen Benutzer zu senden, es sei denn, der Benutzer hat den Bot mindestens einmal gesendet. Einige Kanäle ermöglichen Ausnahmen. Beispielsweise ermöglicht der Teams-Kanal Ihrem Bot, eine proaktive (oder 1 zu 1)-Nachricht an Einzelpersonen in einem bereits eingerichteten Gruppen-Chat zu senden, der den Bot enthält.

Überlegungen zum Entwurf

Beim Implementieren von proaktiven Nachrichten in Ihrem Bot sollten Sie es vermeiden, innerhalb eines kurzen Zeitraums mehrere proaktive Nachrichten zu senden. 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.

Für den einfachsten Typ proaktiver Nachrichten interjektiert der Bot die Nachricht in die Unterhaltung, wenn sie ausgelöst wird, ohne den aktuellen Zustand oder das aktuelle Thema der Unterhaltung zu berücksichtigen. In diesem Szenario unterbricht die proaktive Nachricht den normalen Unterhaltungs-Flow.

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.

Informationen zum proaktiven Turn

Die Fortsetzungsunterhaltungs-Methode verwendet den Unterhaltungsverweis und einen Rückrufhandler für Folgendes:

1. Erstellen Sie einen Turn, in dem die Bot-Anwendung die proaktive Nachricht senden kann. Der Adapter erstellt eine event-Aktivität für diesen Turn, wobei der Name auf „ContinueConversation“ festgelegt ist.
2. Senden Sie den Turn über die Middleware-Pipeline des Adapters.
3. Rufen Sie den Rückrufhandler auf, um benutzerdefinierte Logik auszuführen.

Im Beispiel für proaktive Nachrichten wird der Rückrufhandler im Benachrichtigungscontroller definiert und sendet die Nachricht direkt an die Unterhaltung, ohne die proaktive Aktivität über den normalen Turn-Handler des Bots zu senden. Der Beispielcode greift auch nicht auf den Zustand des Bots zu oder aktualisiert den Zustand des Bots beim proaktiven Aktivieren.

Viele Bots sind zustandsbehaftet und verwenden den Zustand, um eine Unterhaltung über mehrere Turns zu verwalten. Wenn die Fortsetzungsunterhaltungs-Methode einen Turnkontext erstellt, wird der richtige Benutzer- und Unterhaltungszustand zugeordnet und Sie können proaktive Turns in die Logik Ihres Bots integrieren. Wenn Sie möchten, dass die Bot-Logik die proaktive Nachricht erkennt, haben Sie mehrere Möglichkeiten, dies zu tun. Sie können Folgendes ausführen:

• Stellen Sie den Turn-Handler des Bots als Rückrufhandler bereit. Der Bot empfängt dann die Ereignisaktivität „ContinueConversation“.
• Verwenden Sie den Rückrufhandler, um zuerst Informationen zum Turnkontext hinzuzufügen und rufen Sie dann den Turn-Handler des Bots auf.

In beiden Fällen müssen Sie Ihre Bot-Logik entwerfen, um das proaktive Ereignis zu behandeln.

Nächste Schritte

Implementieren eines sequenziellen Konversationsablaufs