Proaktive Nachrichten

Wichtig

Die Codebeispiele in diesem Abschnitt basieren auf Version 4.6 und neueren Versionen des Bot Framework SDK. Wenn Sie nach Dokumentation für frühere Versionen suchen, lesen Sie den Abschnitt "Bots - v3 SDK" im Ressourcenordner der Dokumentation.

Eine proaktive Nachricht ist jede Nachricht, die von einem Bot gesendet wird, die nicht als Antwort auf eine Anforderung eines Benutzers erfolgt. Dies kann Nachrichten umfassen, z. B.:

  • Willkommensnachrichten
  • Benachrichtigungen
  • Geplante Nachrichten

Damit Ihr Bot eine proaktive Nachricht an einen Benutzer, einen Gruppenchat oder ein Team senden kann, muss er Zugriff haben, um die Nachricht zu senden. Für einen Gruppenchat oder ein Team muss die App, die Ihren Bot enthält, zuerst an diesem Speicherort installiert werden. Sie können Ihre App proaktiv mit Microsoft Graph in einem Team installieren, falls erforderlich, oder eine App-Richtlinie verwenden, um Apps an Teams und Benutzer in Ihrem Mandanten zu senden. Für Benutzer muss Ihre App entweder für den Benutzer installiert werden, oder Ihr Benutzer muss Teil eines Teams sein, in dem Ihre App installiert ist.

Das Senden einer proaktiven Nachricht unterscheidet sich vom Senden einer regulären Nachricht. Es ist nicht aktiv turnContext für eine Antwort zu verwenden. Sie müssen die Unterhaltung erstellen, bevor Sie die Nachricht senden. Beispielsweise ein neuer 1:1-Chat oder ein neuer Unterhaltungsthread in einem Kanal. Sie können keinen neuen Gruppenchat oder einen neuen Kanal in einem Team mit proaktiven Nachrichten erstellen.

So senden Sie eine proaktive Nachricht

  1. Rufen Sie bei Bedarf die Benutzer-ID, Team-ID oder Kanal-IDab.
  2. Erstellen Sie die Unterhaltung,falls erforderlich.
  3. Rufen Sie die Unterhaltungs-IDab.
  4. Senden Sie die Nachricht.

Die Codeausschnitte im Beispielabschnitt dienen zum Erstellen einer 1:1-Unterhaltung. Links zum Ausführen von Arbeitsbeispielen für 1:1-Unterhaltungen und Gruppen oder Kanäle finden Sie im Codebeispiel.

Informationen zur effektiven Verwendung proaktiver Nachrichten finden Sie in den bewährten Methoden für proaktives Messaging. Für bestimmte Szenarien müssen Sie Ihre App proaktiv mit Graph installieren. Die Codeausschnitte im Beispielabschnitt dienen zum Erstellen einer 1:1-Unterhaltung. Vollständige Arbeitsbeispiele für 1:1-Unterhaltungen und Gruppen oder Kanäle finden Sie im Codebeispiel.

Abrufen der Benutzer-ID, Team-ID oder Kanal-ID

Zum Erstellen eines neuen Unterhaltungs- oder Unterhaltungsthreads in einem Kanal benötigen Sie die richtige ID. Sie können diese ID mit einer der folgenden Optionen empfangen oder abrufen:

  • Wenn Ihre App in einem bestimmten Kontext installiert ist, erhalten Sie eine onMembersAdded Aktivität.
  • Wenn ein neuer Benutzer zu einem Kontext hinzugefügt wird, in dem Ihre App installiert ist, erhalten Sie eine onMembersAdded Aktivität.
  • Sie können die Liste der Kanäle in einem Team abrufen, in dem Ihre App installiert ist.
  • Sie können die Liste der Mitglieder eines Teams abrufen, in dem Ihre App installiert ist.
  • Jede Aktivität, die Ihr Bot empfängt, muss die erforderlichen Informationen enthalten.

Unabhängig davon, wie Sie die Informationen erhalten, müssen Sie die tenantId und entweder die oder zum Erstellen einer neuen Unterhaltung userId channelId speichern. Sie können den auch teamId verwenden, um einen neuen Unterhaltungsthread im allgemeinen oder Standardkanal eines Teams zu erstellen.

Dies userId ist für Ihre Bot-ID und einen bestimmten Benutzer eindeutig. Sie können die userId zwischen Bots nicht wiederverwenden. Dies channelId ist global. Ihr Bot muss jedoch im Team installiert sein, bevor Sie eine proaktive Nachricht an einen Kanal senden können.

Nachdem Sie die Benutzer- oder Kanalinformationen erhalten haben, müssen Sie die Unterhaltung erstellen.

Erstellen der Unterhaltung

Sie müssen die Unterhaltung erstellen, wenn sie nicht vorhanden ist oder Sie die Unterhaltung nicht conversationId kennen. Sie müssen die Unterhaltung nur einmal erstellen und den Wert oder das conversationId conversationReference Objekt speichern.

Nachdem die Unterhaltung erstellt wurde, müssen Sie die Unterhaltungs-ID abrufen.

Abrufen der Unterhaltungs-ID

Verwenden Sie entweder das conversationReference Objekt oder senden Sie die conversationId tenantId Nachricht. Sie können diese ID abrufen, indem Sie entweder die Unterhaltung erstellen oder sie aus jeder Aktivität speichern, die Aus diesem Kontext an Sie gesendet wird. Store diese ID als Referenz.

Nachdem Sie die entsprechenden Adressinformationen erhalten haben, können Sie Ihre Nachricht senden.

Senden der Nachricht

Nachdem Sie nun über die richtigen Adressinformationen verfügen, können Sie Ihre Nachricht senden. Wenn Sie das SDK verwenden, müssen Sie die continueConversation Methode und die und einen direkten conversationId tenantId API-Aufruf verwenden. Sie müssen den richtigen Wert conversationParameters festlegen, um Ihre Nachricht erfolgreich senden zu können. Sehen Sie sich den Beispielabschnitt an, oder verwenden Sie eines der Im Codebeispielabschnitt aufgeführten Beispiele.

Nachdem Sie die proaktive Nachricht gesendet haben, müssen Sie diese bewährten Methoden befolgen und proaktive Nachrichten senden, um einen besseren Informationsaustausch zwischen Benutzern und dem Bot zu erzielen.

Bewährte Methoden für proaktives Messaging

Das Senden proaktiver Nachrichten an die Benutzer ist eine effektive Möglichkeit, mit Ihren Benutzern zu kommunizieren. Aus Sicht des Benutzers wird die Nachricht jedoch nicht angezeigt. Wenn eine Willkommensnachricht vorhanden ist, ist es das erste Mal, dass sie mit Ihrer App interagiert haben. Es ist wichtig, diese Funktion zu verwenden und dem Benutzer die vollständigen Informationen bereitzustellen, um den Zweck dieser Nachricht zu verstehen.

Willkommensnachrichten

Wenn proaktives Messaging verwendet wird, um eine Willkommensnachricht an einen Benutzer zu senden, gibt es keinen Kontext dafür, warum die Benutzer die Nachricht empfangen. Dies ist auch das erste Mal, dass Benutzer mit Ihrer App interagieren. Es ist eine Gelegenheit, einen guten ersten Eindruck zu erzeugen. Die besten Willkommensnachrichten müssen Folgendes enthalten:

  • Warum ein Benutzer die Nachricht empfängt: Dem Benutzer muss klar sein, warum er die Nachricht empfängt. Wenn Ihr Bot in einem Kanal installiert wurde und Sie eine Willkommensnachricht an alle Benutzer gesendet haben, teilen Sie ihm mit, in welchem Kanal er installiert wurde und wer ihn installiert hat.
  • Was bieten Sie an: Benutzer müssen in der Lage sein, zu erkennen, was sie mit Ihrer App tun können und welchen Wert Sie ihnen bieten können.
  • Was sollten sie als Nächstes tun: Benutzer einladen, einen Befehl auszuprobieren oder mit Ihrer App zu interagieren. Nachrichten mit schlechter Willkommensseite können dazu führen, dass die Benutzer Ihren Bot blockieren. Schreiben Sie auf den Punkt, und löschen Sie Willkommensnachrichten. Iterieren Sie die Willkommensnachrichten, wenn sie nicht den gewünschten Effekt haben.

Benachrichtigungen

Um Benachrichtigungen mithilfe proaktiver Nachrichten zu senden, stellen Sie sicher, dass Ihre Benutzer über einen klaren Pfad verfügen, um allgemeine Aktionen basierend auf Ihrer Benachrichtigung auszuführen. Stellen Sie sicher, dass die Benutzer genau wissen, warum sie eine Benachrichtigung erhalten haben. Gute Benachrichtigungen umfassen im Allgemeinen Folgendes:

  • Was passiert ist: Ein eindeutiger Hinweis darauf, was passiert ist, um die Benachrichtigung zu verursachen.
  • Was war das Ergebnis: Es muss klar sein, welches Element aktualisiert wird, um die Benachrichtigung zu erhalten.
  • Wer oder was ausgelöst wurde: Wer oder welche Aktion ausgeführt wurde, wodurch die Benachrichtigung gesendet wurde.
  • Was können Benutzer als Reaktion tun: Erleichtern Sie Es Ihren Benutzern, Aktionen basierend auf Ihren Benachrichtigungen zu ergreifen.
  • Wie können Benutzer sich abmelden: Sie müssen einen Pfad angeben, über den Benutzer zusätzliche Benachrichtigungen deaktivieren können.

Um Nachrichten an eine große Gruppe von Benutzern zu senden, z. B. an Ihre Organisation, installieren Sie Ihre App proaktiv mit Graph.

Geplante Nachrichten

Wenn Sie proaktive Nachrichten verwenden, um geplante Nachrichten an Benutzer zu senden, überprüfen Sie, ob Ihre Zeitzone auf ihre Zeitzone aktualisiert wurde. Dadurch wird sichergestellt, dass die Nachrichten zum entsprechenden Zeitpunkt an die Benutzer übermittelt werden. Zum Planen von Nachrichten gehören in der Regel:

  • Warum erhält der Benutzer die Nachricht: Machen Sie es Ihren Benutzern leicht, den Grund zu verstehen, aus dem sie die Nachricht erhalten.
  • Was der Benutzer als Nächstes tun kann: Benutzer können die erforderliche Aktion basierend auf dem Nachrichteninhalt ausführen.

Proaktives Installieren Ihrer App mit Graph

Hinweis

Die proaktive Installation von Apps mit Graph befindet sich derzeit in der Betaversion.

Proaktive Meldung von Benutzern, die zuvor nicht installiert oder mit Ihrer App interagiert haben. Sie möchten z. B. den Unternehmenskommunikator verwenden, um Nachrichten an Ihre gesamte Organisation zu senden. In diesem Fall können Sie die Graph-API verwenden, um Ihre App proaktiv für Ihre Benutzer zu installieren. Speichern Sie die erforderlichen Werte aus dem Ereignis zwischen, das conversationUpdate Ihre App bei der Installation empfängt.

Sie können nur Apps installieren, die sich im App-Katalog Ihrer Organisation oder im Teams App-Store befinden.

Informationen zum Installieren von Apps für Benutzer finden Sie in der Dokumentation zu Graph und proaktiver Bot-Installation und Messaging in Teams mit Graph. Es gibt auch ein Microsoft .NET Framework-Beispiel auf der GitHub-Plattform.

Beispiele

Der folgende Code zeigt, wie proaktive Nachrichten gesendet werden:

[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)
    {
        // If you encounter permission-related errors when sending this message, see
        // https://aka.ms/BotTrustServiceUrl
        await turnContext.SendActivityAsync("proactive hello");
    }
}

Hinweis

Derzeit können Bots keinen Gruppenchat über Bot-APIs oder Graph erstellen. createConversation ist nur für 1:1-Chats verfügbar.

Codebeispiel

Die folgende Tabelle enthält ein einfaches Codebeispiel, das den grundlegenden Unterhaltungsfluss in eine Teams Anwendung integriert und wie Sie einen neuen Unterhaltungsthread in einem Kanal in Teams erstellen:

Beispielname Beschreibung .NET Node.js Python
Teams Grundlagen zu Unterhaltungen Veranschaulicht die Grundlagen von Unterhaltungen in Teams, einschließlich des Sendens proaktiver 1:1-Nachrichten. View View View
Starten eines neuen Threads in einem Kanal Veranschaulicht das Erstellen eines neuen Threads in einem Kanal. View View View
Proaktive Installation der App und Senden proaktiver Benachrichtigungen Dieses Beispiel zeigt, wie Sie die proaktive Installation von Apps für Benutzer verwenden und proaktive Benachrichtigungen senden können, indem Sie Microsoft Graph APIs aufrufen. View View

Zusätzliches Codebeispiel

Nächster Schritt

Siehe auch