Unterhaltungsereignisse in Ihrem Teams-Bot

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.

Wenn Sie Ihre Unterhaltungsbots für Microsoft Teams erstellen, können Sie mit Unterhaltungsereignissen arbeiten. Teams sendet Benachrichtigungen an Ihren Bot für Unterhaltungsereignisse, die in Bereichen stattfinden, in denen Ihr Bot aktiv ist. Sie können diese Ereignisse in Ihrem Code erfassen und die folgenden Aktionen ausführen:

  • Lösen Sie eine Willkommensnachricht aus, wenn Ihr Bot zu einem Team hinzugefügt wird.
  • Lösen Sie eine Willkommensnachricht aus, wenn ein neues Teammitglied hinzugefügt oder entfernt wird.
  • Lösen Sie eine Benachrichtigung aus, wenn ein Kanal erstellt, umbenannt oder gelöscht wird.
  • Wenn eine Bot-Nachricht von einem Benutzer gefällt.

Aktualisierungsereignisse in Unterhaltungen

Sie können Unterhaltungsaktualisierungsereignisse verwenden, um bessere Benachrichtigungen und effektivere Botaktionen bereitzustellen.

Wichtig

  • Sie können neue Ereignisse jederzeit hinzufügen, und Ihr Bot beginnt, sie zu empfangen.
  • Sie müssen Ihren Bot so entwerfen, dass er unerwartete Ereignisse empfängt.
  • Wenn Sie das Bot Framework SDK verwenden, antwortet Ihr Bot automatisch mit a 200 - OK auf alle Ereignisse, die Sie nicht behandeln möchten.

Ein Bot empfängt in einem der folgenden Fälle ein conversationUpdate Ereignis:

  • Wenn Bot zu einer Unterhaltung hinzugefügt wurde.
  • Andere Mitglieder werden einer Unterhaltung hinzugefügt oder daraus entfernt.
  • Unterhaltungsmetadaten wurden geändert.

Das conversationUpdate-Ereignis wird an Ihren Bot gesendet, wenn er Informationen zu Mitgliedschaftsaktualisierungen für Teams empfängt, denen er hinzugefügt wurde. Es erhält auch ein Update, wenn es zum ersten Mal für persönliche Unterhaltungen hinzugefügt wurde.

Die folgende Tabelle enthält eine Liste Teams Unterhaltungsaktualisierungsereignisse mit weiteren Details:

Ausgeführte Aktion EventType Aufgerufene Methode Beschreibung Bereich
Kanal erstellt channelCreated OnTeamsChannelCreatedAsync Ein Kanal wird erstellt. Team
Kanal umbenannt channelRenamed OnTeamsChannelRenamedAsync Ein Kanal wird umbenannt. Team
Kanal gelöscht channelDeleted OnTeamsChannelDeletedAsync Ein Kanal wird gelöscht. Team
Kanal wiederhergestellt channelRestored OnTeamsChannelRestoredAsync Ein Kanal wird wiederhergestellt. Team
Mitglieder hinzugefügt membersAdded OnTeamsMembersAddedAsync Ein Element wird hinzugefügt. Alle
Elemente entfernt membersRemoved OnTeamsMembersRemovedAsync Ein Element wird entfernt. groupChat und Team
Team umbenannt teamRenamed OnTeamsTeamRenamedAsync Ein Team wird umbenannt. Team
Team gelöscht teamDeleted OnTeamsTeamDeletedAsync Ein Team wird gelöscht. Team
Team archiviert teamArchived OnTeamsTeamArchivedAsync Ein Team wird archiviert. Team
Team-Archivierung rückgängig gemacht teamUnarchived OnTeamsTeamUnarchivedAsync Ein Team wird nicht archiviert. Team
Team wiederhergestellt teamRestored OnTeamsTeamRestoredAsync Ein Team wird wiederhergestellt Team

Kanal erstellt

Das vom Kanal erstellte Ereignis wird immer dann an Ihren Bot gesendet, wenn ein neuer Kanal in einem Team erstellt wird, in dem Ihr Bot installiert ist.

Der folgende Code zeigt ein Beispiel für ein Kanalerstellungsereignis:

protected override async Task OnTeamsChannelCreatedAsync(ChannelInfo channelInfo, TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    var heroCard = new HeroCard(text: $"{channelInfo.Name} is the Channel created");
    await turnContext.SendActivityAsync(MessageFactory.Attachment(heroCard.ToAttachment()), cancellationToken);
}

Kanal umbenannt

Das umbenannte Kanalereignis wird an Ihren Bot gesendet, wenn ein Kanal in einem Team umbenannt wird, in dem Ihr Bot installiert ist.

Der folgende Code zeigt ein Beispiel für ein Kanal-Umbenennungsereignis:

protected override async Task OnTeamsChannelRenamedAsync(ChannelInfo channelInfo, TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    var heroCard = new HeroCard(text: $"{channelInfo.Name} is the new Channel name");
    await turnContext.SendActivityAsync(MessageFactory.Attachment(heroCard.ToAttachment()), cancellationToken);
}

Kanal gelöscht

Das Ereignis "Kanal gelöscht" wird an Ihren Bot gesendet, sobald ein Kanal in einem Team gelöscht wird, in dem Ihr Bot installiert ist.

Der folgende Code zeigt ein Beispiel für das Ereignis "Kanal gelöscht":

protected override async Task OnTeamsChannelDeletedAsync(ChannelInfo channelInfo, TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    var heroCard = new HeroCard(text: $"{channelInfo.Name} is the Channel deleted");
    await turnContext.SendActivityAsync(MessageFactory.Attachment(heroCard.ToAttachment()), cancellationToken);
}

Kanal wiederhergestellt

Das Wiederherstellungsereignis des Kanals wird an Ihren Bot gesendet, sobald ein Kanal, der zuvor gelöscht wurde, in einem Team wiederhergestellt wird, in dem Ihr Bot bereits installiert ist.

Der folgende Code zeigt ein Beispiel für ein Wiederherstellungsereignis des Kanals:

protected override async Task OnTeamsChannelRestoredAsync(ChannelInfo channelInfo, TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    var heroCard = new HeroCard(text: $"{channelInfo.Name} is the Channel restored.");
    await turnContext.SendActivityAsync(MessageFactory.Attachment(heroCard.ToAttachment()), cancellationToken);
}

Teammitglieder hinzugefügt

Das teamMemberAdded Ereignis wird an Ihren Bot gesendet, wenn es zum ersten Mal zu einer Unterhaltung hinzugefügt wird. Das Ereignis wird jedes Mal an Ihren Bot gesendet, wenn ein neuer Benutzer zu einem Team- oder Gruppenchat hinzugefügt wird, in dem Ihr Bot installiert ist. Die Benutzerinformationen, die ID sind, sind für Ihren Bot eindeutig und können für die zukünftige Verwendung durch Ihren Dienst zwischengespeichert werden, z. B. das Senden einer Nachricht an einen bestimmten Benutzer.

Der folgende Code zeigt ein Beispiel für das hinzugefügte Ereignis für Teammitglieder:

protected override async Task OnTeamsMembersAddedAsync(IList<TeamsChannelAccount> teamsMembersAdded , TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    foreach (TeamsChannelAccount member in teamsMembersAdded)
    {
        if (member.Id == turnContext.Activity.Recipient.Id)
        {
            // Send a message to introduce the bot to the team
            var heroCard = new HeroCard(text: $"The {member.Name} bot has joined {teamInfo.Name}");
            await turnContext.SendActivityAsync(MessageFactory.Attachment(heroCard.ToAttachment()), cancellationToken);
        }
        else
        {
            var heroCard = new HeroCard(text: $"{member.Name} joined {teamInfo.Name}");
            await turnContext.SendActivityAsync(MessageFactory.Attachment(heroCard.ToAttachment()), cancellationToken);
        }
    }
}

Teammitglieder entfernt

Das teamMemberRemoved Ereignis wird an Ihren Bot gesendet, wenn es aus einem Team entfernt wird. Das Ereignis wird jedes Mal an Ihren Bot gesendet, wenn ein Beliebiger Benutzer aus einem Team entfernt wird, in dem Ihr Bot Mitglied ist. Um festzustellen, ob das neue Mitglied entfernt wurde, der Bot selbst oder ein Benutzer war, überprüfen Sie das Activity Objekt des turnContext . Wenn das Id Feld des Objekts mit dem Feld des Objekts identisch MembersRemoved Id Recipient ist, ist das entfernte Element der Bot, andernfalls ein Benutzer. Der Bot Id ist im Allgemeinen 28:<MicrosoftAppId> .

Hinweis

Wenn ein Benutzer dauerhaft aus einem Mandanten gelöscht wird, membersRemoved conversationUpdate wird das Ereignis ausgelöst.

Der folgende Code zeigt ein Beispiel für ein Ereignis, bei dem Teammitglieder entfernt wurden:

protected override async Task OnTeamsMembersRemovedAsync(IList<ChannelAccount> membersRemoved, TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    foreach (TeamsChannelAccount member in membersRemoved)
    {
        if (member.Id == turnContext.Activity.Recipient.Id)
        {
            // The bot was removed
            // You should clear any cached data you have for this team
        }
        else
        {
            var heroCard = new HeroCard(text: $"{member.Name} was removed from {teamInfo.Name}");
            await turnContext.SendActivityAsync(MessageFactory.Attachment(heroCard.ToAttachment()), cancellationToken);
        }
    }
}

Team umbenannt

Ihr Bot wird benachrichtigt, wenn das Team umbenannt wird. Es empfängt ein conversationUpdate Ereignis mit eventType.teamRenamed im channelData Objekt.

Der folgende Code zeigt ein Beispiel für ein umbenanntes Teamereignis:

protected override async Task OnTeamsTeamRenamedAsync(TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    var heroCard = new HeroCard(text: $"{teamInfo.Name} is the new Team name");
    await turnContext.SendActivityAsync(MessageFactory.Attachment(heroCard.ToAttachment()), cancellationToken);
}

Team gelöscht

Ihr Bot wird benachrichtigt, wenn das Team gelöscht wird. Es empfängt ein conversationUpdate Ereignis mit eventType.teamDeleted im channelData Objekt.

Der folgende Code zeigt ein Beispiel für ein Team-Deleted-Ereignis:

protected override async Task OnTeamsTeamDeletedAsync(TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    //handle delete event
}

Team wiederhergestellt

Der Bot erhält eine Benachrichtigung, wenn ein Team nach dem Löschen wiederhergestellt wird. Es empfängt ein conversationUpdate Ereignis mit eventType.teamrestored im channelData Objekt.

Der folgende Code zeigt ein Beispiel für ein Wiederherstellungsereignis des Teams:

protected override async Task OnTeamsTeamrestoredAsync(TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    var heroCard = new HeroCard(text: $"{teamInfo.Name} is the team name");
    await turnContext.SendActivityAsync(MessageFactory.Attachment(heroCard.ToAttachment()), cancellationToken);
}

Team archiviert

Der Bot erhält eine Benachrichtigung, wenn das Team installiert und archiviert wird. Es empfängt ein conversationUpdate Ereignis mit eventType.teamarchived im channelData Objekt.

Der folgende Code zeigt ein Beispiel für ein teamarchiviertes Ereignis:

protected override async Task OnTeamsTeamArchivedAsync(TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    var heroCard = new HeroCard(text: $"{teamInfo.Name} is the team name");
    await turnContext.SendActivityAsync(MessageFactory.Attachment(heroCard.ToAttachment()), cancellationToken);
}

Team-Archivierung rückgängig gemacht

Der Bot erhält eine Benachrichtigung, wenn das Team installiert und nicht archiviert wird. Es empfängt ein conversationUpdate Ereignis mit eventType.teamUnarchived im channelData Objekt.

Der folgende Code zeigt ein Beispiel für ein Nichtarchiviertes Teamereignis:

protected override async Task OnTeamsTeamUnarchivedAsync(TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    var heroCard = new HeroCard(text: $"{teamInfo.Name} is the team name");
    await turnContext.SendActivityAsync(MessageFactory.Attachment(heroCard.ToAttachment()), cancellationToken);
}

Nachdem Sie nun mit den Unterhaltungsaktualisierungsereignissen gearbeitet haben, können Sie die Nachrichtenreaktionsereignisse verstehen, die für unterschiedliche Reaktionen auf eine Nachricht auftreten.

Nachrichtenreaktionsereignisse

Das messageReaction Ereignis wird gesendet, wenn ein Benutzer Reaktionen auf eine Nachricht hinzufügt oder entfernt, die von Ihrem Bot gesendet wurde. Die replyToId enthält die ID der Nachricht und die Art der Reaktion im Type Textformat. Die Arten von Reaktionen umfassen Zärtlich, Herz, Heiterkeit, z. B. "Leider" und "Überrascht". Dieses Ereignis enthält nicht den Inhalt der ursprünglichen Nachricht. Wenn die Verarbeitung von Reaktionen auf Ihre Nachrichten für Ihren Bot wichtig ist, müssen Sie die Nachrichten beim Senden speichern. Die folgende Tabelle enthält weitere Informationen zum Ereignistyp und zu Nutzlastobjekten:

EventType Payload-Objekt Beschreibung Bereich
messageReaction reactionsAdded Reaktionen zu Bot-Nachricht hinzugefügt. Alle
messageReaction reactionsRemoved Reaktionen aus Bot-Nachricht entfernt. Alle

Reaktionen, die zu Bot-Nachrichten hinzugefügt wurden

Der folgende Code zeigt ein Beispiel für Reaktionen auf eine Bot-Nachricht:

protected override async Task OnReactionsAddedAsync(IList<MessageReaction> messageReactions, ITurnContext<IMessageReactionActivity> turnContext, CancellationToken cancellationToken)
{
    foreach (var reaction in messageReactions)
    {
      var newReaction = $"You reacted with '{reaction.Type}' to the following message: '{turnContext.Activity.ReplyToId}'";
      var replyActivity = MessageFactory.Text(newReaction);
      var resourceResponse = await turnContext.SendActivityAsync(replyActivity, cancellationToken);
    }
}

Reaktionen aus Bot-Nachricht entfernt

Der folgende Code zeigt ein Beispiel für Reaktionen, die aus der Bot-Nachricht entfernt wurden:

protected override async Task OnReactionsRemovedAsync(IList<MessageReaction> messageReactions, ITurnContext<IMessageReactionActivity> turnContext, CancellationToken cancellationToken)
{
    foreach (var reaction in messageReactions)
    {
      var newReaction = $"You removed the reaction '{reaction.Type}' from the following message: '{turnContext.Activity.ReplyToId}'";
      var replyActivity = MessageFactory.Text(newReaction);
      var resourceResponse = await turnContext.SendActivityAsync(replyActivity, cancellationToken);
    }
}

Installationsupdateereignis

Der Bot empfängt ein installationUpdate Ereignis, wenn Sie einen Bot in einem Unterhaltungsthread installieren. Die Deinstallation des Bots aus dem Thread löst auch das Ereignis aus. Bei der Installation eines Bots wird das Aktionsfeld im Ereignis so festgelegt, dass es hinzugefügt wird, und wenn der Bot deinstalliert wird, wird das Aktionsfeld so festgelegt, dass es entfernt wird.

Hinweis

Wenn Sie eine Anwendung aktualisieren und dann einen Bot hinzufügen oder entfernen, löst die Aktion auch das installationUpdate Ereignis aus. Das Aktionsfeld wird auf "Add-Upgrade" festgelegt, wenn Sie einen Bot hinzufügen, oder "remove-upgrade", wenn Sie einen Bot entfernen.

Updateereignis installieren

Verwenden Sie das Ereignis, um bei der installationUpdate Installation eine Einführungsnachricht von Ihrem Bot zu senden. Dieses Ereignis hilft Ihnen, Ihre Datenschutz- und Datenaufbewahrungsanforderungen zu erfüllen. Sie können auch Benutzer- oder Threaddaten bereinigen und löschen, wenn der Bot deinstalliert wird.

protected override async Task
OnInstallationUpdateActivityAsync(ITurnContext<IInstallationUpdateActivity> turnContext, CancellationToken cancellationToken) {
var activity = turnContext.Activity; if
(string.Equals(activity.Action, "Add",
StringComparison.InvariantCultureIgnoreCase)) {
// TO:DO Installation workflow }
else
{ // TO:DO Uninstallation workflow
} return; }

Sie können auch einen dedizierten Handler zum Hinzufügen oder Entfernen von Szenarien als alternative Methode verwenden, um ein Ereignis zu erfassen.

protected override async Task
OnInstallationUpdateAddAsync(ITurnContext<IInstallationUpdateActivity>
turnContext, CancellationToken cancellationToken) {
// TO:DO Installation workflow return;
}

Deinstallationsverhalten für persönliche Apps mit Bot

Hinweis

Das Deinstallationsverhalten für persönliche Apps mit Bot ist derzeit nur in der öffentlichen Entwicklervorschauverfügbar.

Wenn Sie eine App deinstallieren, wird der Bot ebenfalls deinstalliert. Wenn ein Benutzer eine Nachricht an Ihre App sendet, erhält er den Antwortcode 403. Ihr Bot erhält einen 403-Antwortcode für neue Nachrichten, die von Ihrem Bot gepostet wurden. Das Verhalten der Postdeinstallation für Bots im persönlichen Bereich mit den Bereichen Teams und groupChat wird nun ausgerichtet. Sie können keine Nachrichten senden oder empfangen, nachdem eine App deinstalliert wurde.

Uninstall event

Ereignisbehandlung für Installations- und Deinstallationsereignisse

Wenn Sie diese Installations- und Deinstallationsereignisse verwenden, gibt es einige Fälle, in denen Bots Ausnahmen beim Empfangen unerwarteter Ereignisse von Teams gewähren. Dies geschieht in den folgenden Fällen:

  • Sie erstellen Ihren Bot ohne das Microsoft Bot Framework SDK, und daher gibt der Bot eine Ausnahme beim Empfangen eines unerwarteten Ereignisses aus.
  • Sie erstellen Ihren Bot mit dem Microsoft Bot Framework SDK, und Sie können das Standardereignisverhalten ändern, indem Sie das Basisereignishandle überschreiben.

Es ist wichtig zu wissen, dass neue Ereignisse jederzeit in der Zukunft hinzugefügt werden können und Ihr Bot beginnt, sie zu empfangen. Daher müssen Sie die Möglichkeit entwerfen, unerwartete Ereignisse zu empfangen. Wenn Sie das Bot Framework SDK verwenden, antwortet Ihr Bot automatisch mit einem 200 – OK auf alle Ereignisse, die Sie nicht behandeln möchten.

Codebeispiel

Beispielname Beschreibung .NET Node.js Python
Unterhaltungsbot Beispielcode für Bots-Unterhaltungsereignisse. View View View

Nächster Schritt