Proaktive Nachrichten
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 proaktive Nachrichten zu senden, wird empfohlen, mit dem Erstellen eines Benachrichtigungsbots mit JavaScript oder dem Beispiel für eingehende Webhookbenachrichtigungen zu beginnen. Laden Sie zunächst Teams Toolkit explore herunter. Weitere Informationen finden Sie unter Teams Toolkit-Dokumente.
Bots sind in Den Umgebungen Government Community Cloud (GCC), GCC-High und Department of Defense (DOD) verfügbar. Für proaktive Nachrichten müssen die Bots die folgenden Endpunkte für Behörden-Cloudumgebungen verwenden:
-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
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:
- Rufen Sie bei Bedarf die Microsoft Entra Benutzer-ID, Benutzer-ID, Team-ID oder Kanal-ID ab.
- Erstellen der Unterhaltung, falls erforderlich.
- Abrufen der Konversations-ID.
- 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 mitaadObjectId
nicht in einem persönlichen Bereich installiert ist, gibt der Bot einen Fehler mitForbiddenOperationException
einer403
Meldung zurück.Die
userId
ist für Ihre Bot-ID und einen bestimmten Benutzer eindeutig. Sie können dieuserId
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 Unterhaltung erstellen, wenn sie nicht vorhanden ist oder Sie nicht conversationId
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 aadObjectId
userId
, tenantId
und serviceUrl
.
Verwenden Sie für serviceUrl
den 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 conversationId
abzurufen.
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 eine Begrüßungsnachricht angezeigt wird, markiert sie die erste Interaktion mit Ihrer App. 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. Wenn Benutzeraktionen in einer Registerkarten-App erforderlich sind, verwenden Sie Aktivitätsfeedbenachrichtigungen anstelle eines Bots. Stellen Sie sicher, dass Benutzer über ein klares Verständnis dafür verfügen, warum sie eine Benachrichtigung erhalten haben. Zu den guten Benachrichtigungen gehören 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 hat Maßnahmen ergriffen, die das Senden der Benachrichtigung verursacht haben.
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.
So aktualisieren oder löschen Sie eine proaktive Nachricht, die von einem Benachrichtigungsbot gesendet wird:
Verfolgen Sie die gesendeten Nachrichten, indem Sie ihre Nachrichten-IDs oder Konversationsverweise beim Senden der proaktiven Nachricht speichern.
Verwenden Sie
UpdateActivityAsync
die Methoden oderDeleteActivityAsync
, um die ursprüngliche Nachricht zu aktualisieren oder zu löschen.
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. Zu den Geplanten Meldungen gehören:
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 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
undactivityId
in den Anforderungsendpunkt ein. Um dieses Szenario abzuschließen, müssen Sie den zwischenspeichern, deractivity 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 | – |
Nächster Schritt
Siehe auch
- Codebeispiele für proaktives Messaging in Teams
- Kanal- und Gruppenchatunterhaltungen mit einem Bot
- Reagieren auf die Aktion zum Senden des Dialogfelds
- Proaktive Benachrichtigungen an Benutzer senden
- Erstellen Ihrer ersten Bot-App mit JavaScript
- Erstellen eines Benachrichtigungsbots mit JavaScript zum Senden einer proaktiven Nachricht
- TurnContext
- Implementieren von benutzerdefiniertem Speicher für Bots