Proaktive Nachrichten

  • Artikel

Wichtig

Die Codebeispiele in diesem Abschnitt basieren auf Version 4.6 und höheren Versionen des Bot Framework SDK. Wenn Sie nach Dokumentation zu früheren Versionen suchen, lesen Sie den Abschnitt bots – v3 SDK im Ordner Legacy SDKs der Dokumentation.

Eine proaktive Nachricht ist jede Nachricht, die von einem Bot gesendet wird, die nicht als Antwort auf eine Anforderung eines Benutzers gesendet wurde. Diese Nachricht kann Inhalte enthalten, z. B.:

  • Willkommensnachrichten
  • Benachrichtigungen
  • Geplante Nachrichten

Wichtig

Um eine proaktive Nachricht an einen Benutzer, einen Gruppenchat oder ein Team zu senden, muss Ihr Bot über den erforderlichen Zugriff zum Senden der Nachricht verfügen. 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 bei Bedarf proaktiv mithilfe von Microsoft Graph in einem Team installieren oder eine benutzerdefinierte App-Richtlinie verwenden, um eine App in Ihren Teams und für die Benutzer von organization zu installieren. Für bestimmte Szenarien müssen Sie Ihre App proaktiv mithilfe von Graph installieren. Damit ein Benutzer proaktive Nachrichten erhält, installieren Sie die App für den Benutzer, oder machen Sie den Benutzer zu einem Teil eines Teams, in dem die App installiert ist.

Das Senden einer proaktiven Nachricht unterscheidet sich vom Senden einer regulären Nachricht. Es ist keine aktive turnContext für eine Antwort vorhanden. 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 proaktivem Messaging erstellen.

Folgen Sie diesen Schritten, um eine proaktive Nachricht zu senden:

  1. Rufen Sie bei Bedarf die Microsoft Entra Benutzer-ID, Benutzer-ID, Team-ID oder Kanal-ID ab.
  2. Erstellen der Unterhaltung, falls erforderlich.
  3. Abrufen der Konversations-ID.
  4. Senden der Nachricht.

Die Codeausschnitte im Beispielabschnitt dienen zum Erstellen einer 1:1-Unterhaltung. Links zu Beispielen für 1:1-Unterhaltungen und Gruppen- oder Kanalnachrichten finden Sie im Codebeispiel. Informationen zur effektiven Verwendung proaktiver Nachrichten finden Sie unter Bewährte Methoden für proaktives Messaging.

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

Sie können eine neue Unterhaltung mit einem Benutzer oder einem Unterhaltungsthread in einem Kanal erstellen, und Sie müssen über die richtige ID verfügen. Sie können diese ID auf eine der folgenden Arten 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.
  • Jedes Ereignis, das der Bot empfängt, enthält die erforderlichen Informationen, die Sie aus dem Botkontext (TurnContext-Objekt) abrufen können.
  • Sie können in einem Team, in dem Ihre App installiert ist, die Liste der Kanäle abrufen.
  • Sie können die Liste der Mitglieder eines Teams abrufen, in dem Ihre App installiert ist.

Speichern Sie unabhängig davon, wie Sie die Informationen erhalten, tenantId und speichern Sie dann entweder oder userId, channelId um eine neue Unterhaltung zu erstellen. Sie können auch die teamId verwenden, um einen neuen Unterhaltungsthread im allgemeinen oder Standardkanal eines Teams zu erstellen. Stellen Sie sicher, dass der Bot im Team installiert ist, bevor Sie eine proaktive Nachricht an einen Kanal senden können.

  • ist aadObjectId für den Benutzer eindeutig und kann mithilfe der Graph-API abgerufen werden, um eine neue Unterhaltung im persönlichen Chat zu erstellen. Stellen Sie sicher, dass der Bot im persönlichen Bereich installiert ist, bevor Sie eine proaktive Nachricht senden können. Wenn der Bot beim Senden einer proaktiven Nachricht mit aadObjectIdnicht in einem persönlichen Bereich installiert ist, gibt der Bot einen Fehler mit ForbiddenOperationException einer 403 Meldung zurück.

  • Die userId ist für Ihre Bot-ID und einen bestimmten Benutzer eindeutig. Sie können die userId zwischen Bots nicht wiederverwenden.

  • Die channelId ist global.

Erstellen Sie die Unterhaltung, nachdem Sie über die Benutzer- oder Kanalinformationen verfügen.

Hinweis

Das Senden proaktiver Nachrichten mit aadObjectId wird nur im persönlichen Bereich unterstützt.

Erstellen der Unterhaltung

Sie können die Konversation erstellen, wenn sie nicht vorhanden ist oder Sie die conversationIdnicht kennen. Erstellen Sie die Konversation nur einmal, und speichern Sie den Wert oder conversationReference das conversationId Objekt.

Zum Erstellen der Unterhaltung benötigen Sie oder aadObjectIduserId, tenantIdund serviceUrl.

Verwenden Sie für serviceUrlden Wert einer eingehenden Aktivität, die den Flow auslöst, oder eine der globalen Dienst-URLs. Wenn von einer eingehenden Aktivität, die serviceUrl das proaktive Szenario auslöst, nicht verfügbar ist, verwenden Sie die folgenden globalen URL-Endpunkte:

  • Öffentlich: https://smba.trafficmanager.net/teams/
  • GCC: https://smba.infra.gcc.teams.microsoft.com/teams
  • GCCH: https://smba.infra.gov.teams.microsoft.us/teams
  • DOD: https://smba.infra.dod.teams.microsoft.us/teams

Ein Codebeispiel finden Sie unter dem Aufruf CreateConversationAsync im Beispiel.

Sie können die Unterhaltung abrufen, wenn die App zum ersten Mal installiert wird. Nachdem die Unterhaltung erstellt wurde, rufen Sie die Konversations-ID ab. Die conversationId ist in den Aktualisierungsereignissen der Unterhaltung verfügbar.

Die Konversations-ID ist für jeden Bot innerhalb eines bestimmten Kanals eindeutig, auch in einer mehrinstanzenfähigen Umgebung. Diese ID stellt sicher, dass die Nachrichten des Bots an den entsprechenden Kanal weitergeleitet werden und nicht mit anderen Bots oder Kanälen innerhalb desselben oder in verschiedenen Organisationen unterbrochen werden.

Wenn Sie nicht über verfügen conversationId, können Sie Ihre App proaktiv mithilfe von Graph installieren , um die conversationIdabzurufen.

Abrufen der Konversations-ID

Verwenden Sie entweder das conversationReference-Objekt oder conversationId und tenantId, um die Nachricht zu senden. Sie können diese ID abrufen, indem Sie entweder die Konversation erstellen oder sie aus jeder Aktivität speichern, die aus diesem Kontext an Sie gesendet wird. Speichern Sie 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 sowie die conversationId und tenantId verwenden, um einen direkten API-Aufruf zu tätigen. Um Ihre Nachricht zu senden, legen Sie fest conversationParameters. Sehen Sie sich den Abschnitt Beispiele an, oder verwenden Sie eines der Beispiele, die im Abschnitt Codebeispiel aufgeführt sind.

Hinweis

Teams unterstützt das Senden proaktiver Nachrichten mit E-Mail oder Benutzerprinzipalname (User Principal Name, UPN) nicht.

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 ermöglichen.

Im folgenden Video erfahren Sie, wie Sie proaktive Nachrichten aus Bots senden:



Verstehen, wer einen Bot blockiert, stummgeschaltet oder deinstalliert hat

Als Entwickler können Sie einen Bericht erstellen, um zu verstehen, welche Benutzer in Ihrer organization einen Bot blockiert, stummgeschaltet oder deinstalliert haben. Diese Informationen können den Administratoren Ihres organization dabei helfen, organisationsweite Nachrichten zu übertragen oder die App-Nutzung zu fördern.

Mithilfe von Teams können Sie eine proaktive Nachricht an den Bot senden, um zu überprüfen, ob ein Benutzer einen Bot blockiert oder deinstalliert hat. Wenn der Bot blockiert oder deinstalliert wird, gibt Teams einen 403 Antwortcode mit einem zurück subCode: MessageWritesBlocked. Diese Antwort gibt an, dass die vom Bot gesendete Nachricht nicht an den Benutzer übermittelt wird.

Der Antwortcode wird pro Benutzer gesendet und enthält die Identität des Benutzers. Sie können die Antwortcodes für jeden Benutzer zusammen mit seiner Identität kompilieren, um einen Bericht aller Benutzer zu erstellen, die den Bot blockiert haben.

Ein Beispiel für den Antwortcode 403 finden Sie unten.


HTTP/1.1 403 Forbidden

Cache-Control: no-store, must-revalidate, no-cache

 Pragma: no-cache

 Content-Length: 196

 Content-Type: application/json; charset=utf-8

 Server: Microsoft-HTTPAPI/2.0

 Strict-Transport-Security: max-age=31536000; includeSubDomains

 MS-CV: NXZpLk030UGsuHjPdwyhLw.5.0

 ContextId: tcid=0,server=msgapi-canary-eus2-0,cv=NXZpLk030UGsuHjPdwyhLw.5.0

 Date: Tue, 29 Mar 2022 17:34:33 GMT

{"errorCode":209,"message":"{\r\n  \"subCode\": \"MessageWritesBlocked\",\r\n  \"details\": \"Thread is blocked from message writes.\",\r\n  \"errorCode\": null,\r\n  \"errorSubCode\": null\r\n}"}

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 unaufgefordert angezeigt. Wenn es eine Willkommensnachricht gibt, ist dies das erste Mal, dass er mit Ihrer App interagiert. Es ist wichtig, diese Funktion zu verwenden und dem Benutzer die vollständigen Informationen bereitzustellen, damit sie den Zweck dieser Nachricht verstehen.

Willkommensnachrichten

Wenn proaktives Messaging verwendet wird, um eine Willkommensnachricht an einen Benutzer zu senden, gibt es keinen Kontext, warum der Benutzer die Nachricht empfängt. Außerdem ist dies die erste Interaktion des Benutzers mit Ihrer App. Es ist eine Gelegenheit, für einen guten ersten Eindruck zu sorgen. Eine gute Benutzererfahrung sorgt für eine bessere Akzeptanz der App. Schlechte Begrüßungsnachrichten können dazu führen, dass Benutzer Ihre App blockieren. Schreiben Sie eine klare Begrüßungsnachricht, und durchlaufen Sie die Willkommensnachricht, wenn sie nicht die gewünschte Wirkung hat.

Eine gute Begrüßungsnachricht kann Folgendes enthalten:

  • Grund für die Nachricht: Dem Benutzer muss klar sein, warum er die Nachricht empfängt. Wenn Ihr Bot in einem Kanal installiert wurde und Sie allen Benutzern eine Willkommensnachricht gesendet haben, teilen Sie ihnen mit, in welchem Kanal er installiert wurde und wer ihn installiert hat.

  • Ihr Angebot: Benutzer müssen in der Lage sein zu identifizieren, was sie mit Ihrer App tun können und welchen Wert Sie ihnen bringen können.

  • Nächste Schritte: Benutzer sollten die nächsten Schritte verstehen. Laden Sie z. B. Benutzer ein, einen Befehl auszuprobieren oder mit Ihrer App zu interagieren.

Benachrichtigungen

Um Benachrichtigungen mit proaktivem Messaging zu senden, stellen Sie sicher, dass Ihre Benutzer einen eindeutigen Pfad haben, um allgemeine Aktionen basierend auf Ihrer Benachrichtigung auszuführen. Stellen Sie sicher, dass Benutzer über ein klares Verständnis dafür verfügen, warum sie eine Benachrichtigung erhalten haben. Gute Benachrichtigungen umfassen im Allgemeinen die folgenden Elemente:

  • Was ist geschehen? Klare Angaben dazu, wodurch die Benachrichtigung ausgelöst wurde.

  • Was war das Ergebnis? Es muss klar sein, welches Element aktualisiert wird, um die Benachrichtigung zu erhalten.

  • Wer oder was hat es ausgelöst? Wer oder was eine Aktion ergriffen hat, was dazu geführt hat, dass die Benachrichtigung gesendet wurde.

  • Was können die Benutzer als Reaktion darauf tun? Erleichtern Sie es Ihren Benutzern, Aktionen basierend auf Ihren Benachrichtigungen durchzuführen.

  • Wie können Benutzer sich vom Erhalt von Benachrichtigungen abmelden? Sie müssen einen Pfad angeben, unter dem Benutzer weitere 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 mithilfe von Graph.

Geplante Nachrichten

Wenn Sie proaktives Messaging 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. Geplante Nachrichten umfassen in der Regel Folgendes:

  • Warum erhält der Benutzer die Nachricht? Erleichtern Sie es Ihren Benutzern, zu verstehen, warum sie die Nachricht erhalten.

  • Was kann der Benutzer als Nächstes tun? Benutzer können die erforderliche Aktion basierend auf dem Nachrichteninhalt ausführen.

Proaktives Installieren Ihrer App mit Graph

Proaktive Nachricht an Benutzer senden, die Ihre App zuvor nicht installiert oder mit Ihr interagiert haben. Sie sollten beispielsweise den Unternehmens-Communicator 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 conversationUpdate Ereignis zwischen, das Ihre App bei der Installation empfängt.

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

Weitere Informationen finden Sie unter Installieren von Apps für Benutzer in der Graph-Dokumentation und proaktive Botinstallation und -messaging in Teams mit Graph. Es gibt auch ein Microsoft .NET Frameworkbeispiel auf der GitHub-Plattform.

Beispiele

Stellen Sie sicher, dass Sie sich authentifizieren und über ein Bearertoken verfügen, bevor Sie mithilfe der REST-API eine neue Konversation erstellen. Im Folgenden sind die REST-API aufgeführt, um eine Unterhaltung in verschiedenen Kontexten zu erstellen:

  • REST-API zum Erstellen einer Unterhaltung in einem Einzelchat.

  • REST-API zum Erstellen einer Unterhaltung in einem Kanal.

  • REST-API zum Aktualisieren der Nachricht in einer Unterhaltung: Um eine vorhandene Aktivität innerhalb einer Unterhaltung zu aktualisieren, schließen Sie die conversationId und activityId in den Anforderungsendpunkt ein. Um dieses Szenario abzuschließen, müssen Sie die vom ursprünglichen POST-Aufruf zurückgegebene Aktivitäts-ID zwischenspeichern.

    PUT {Service URL of your bot}/v3/conversations/{conversationId}/activities/{activityId}

    
{
    "type": "message",
    "text": "This message has been updated"
}

    Um eine vorhandene Aktivität innerhalb einer Unterhaltung zu aktualisieren, schließen Sie conversationId und activityId in den Anforderungsendpunkt ein. Um dieses Szenario abzuschließen, müssen Sie den zwischenspeichern, der activity ID vom ursprünglichen Post-Aufruf zurückgegeben wurde. Wenn der Aufruf erfolgreich ist, gibt die API das folgende Antwortobjekt zurück.

    {
    "id": "{{activityID}}"
}

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)
        {
            var newReference = new ConversationReference()
            {
                Bot = new ChannelAccount()
                {
                    Id = conversationReference.Bot.Id
                },
                Conversation = new ConversationAccount()
                {
                    Id = conversationReference.Conversation.Id
                },
                ServiceUrl = conversationReference.ServiceUrl,
            };

            // Sends a proactive message from the bot to a conversation.
            await ((BotAdapter)_adapter).ContinueConversationAsync(_appId, newReference, 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://learn.microsoft.com/en-us/azure/bot-service/bot-builder-howto-proactive-message?view=azure-bot-service-4.0&tabs=csharp#avoiding-401-unauthorized-errors
        // Sends an activity to the sender of the incoming activity.
        await turnContext.SendActivityAsync("proactive hello");
    }
}

Beispiel für einen Codeausschnitt zum Veranschaulichen der Erstellung eines Konversationsverweises.

 var newReference = new ConversationReference()
        {
            Bot = new ChannelAccount()
            {
                Id = conversationReference.Bot.Id
            },
            Conversation = new ConversationAccount()
            {
                Id = conversationReference.Conversation.Id
            },
            ServiceUrl = conversationReference.ServiceUrl,
        };

Codebeispiel

Die folgende Tabelle enthält ein einfaches Codebeispiel, das den grundlegenden Konversationsfluss in eine Microsoft Teams-Anwendung einbezieht und wie Sie einen neuen Konversationsthread in einem Kanal in Microsoft Teams erstellen:

Beispielname Beschreibung .NET Node.js Python Manifest
Grundlagen zu Teams-Unterhaltungen In dieser Beispiel-App wird gezeigt, wie verschiedene Botunterhaltungsereignisse verwendet werden, die in Bot Framework v4 für den persönlichen Bereich und den Teams-Bereich verfügbar sind. View View View View
Starten eines neuen Threads in einem Kanal In diesem Beispiel wird gezeigt, wie Sie einen Thread in einem bestimmten Teamkanal mit Bot Framework v4 starten. View View View View
Proaktive Installation der App und Senden proaktiver Benachrichtigungen Dieses Beispiel zeigt, wie Sie die proaktive Installation der App für Benutzer verwenden und proaktive Benachrichtigungen senden können, indem Sie Microsoft Graph APIs aufrufen. View View – View
Proaktives Messaging Dies ist ein Beispiel, das zeigt, wie Die Konversationsverweisinformationen des Benutzers gespeichert werden, um eine proaktive Erinnerungsnachricht mithilfe von Bots zu senden. View View –

Weitere Codebeispiele für proaktives Messaging

Nächster Schritt

Formatieren von Bot-Nachrichten

Siehe auch