Subscribe to conversation events

Important

The code samples in this section are based on 4.6 and later versions of the Bot Framework SDK. If you're looking for documentation for earlier versions, see the Bots - v3 SDK section in the Resources folder of the documentation.

Microsoft Teams sends notifications to your bot for events that happen in scopes where your bot is active. You can capture these events in your code and take action on them, such as the following:

  • Trigger a welcome message when your bot is added to a team
  • Trigger a welcome message when a new team member is added or removed
  • Trigger a notification when a channel is created, renamed or deleted
  • When a bot message is liked by a user

Conversation update events

A bot receives a conversationUpdate event when it has been added to a conversation, other members have been added to or removed from a conversation, or conversation metadata has changed.

The conversationUpdate event is sent to your bot when it receives information on membership updates for teams where it has been added. It also receives an update when it has been added for the first time specifically for personal conversations.

The following table shows a list of Teams conversation update events, with links to more details.

Action Taken EventType Method Called Description Scope
channel created channelCreated OnTeamsChannelCreatedAsync A channel was created Team
channel renamed channelRenamed OnTeamsChannelRenamedAsync A channel was renamed Team
channel deleted channelDeleted OnTeamsChannelDeletedAsync A channel was deleted Team
team members added teamMemberAdded OnTeamsMembersAddedAsync A Member added to team All
team members removed teamMemberRemoved OnTeamsMembersRemovedAsync A Member was removed from team groupChat & team
team renamed teamRenamed OnTeamsTeamRenamedAsync A Team was renamed Team

Channel created

The channel created event is sent to your bot whenever a new channel is created in a team your bot is installed in.

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

Channel renamed

The channel renamed event is sent to your bot whenever a channel is renamed in a team your bot is installed in.

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

Channel Deleted

The channel deleted event is sent to your bot whenever a channel is deleted in a team your bot is installed in.

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

Team members added

The teamMemberAdded event is sent to your bot the first time it is added to a conversation and every time a new user is added to a team or group chat that your bot is installed in. The user information (ID) is unique for your bot and can be cached for future use by your service (such as sending a message to a specific user).

protected override async Task OnTeamsMembersAddedAsync(IList<ChannelAccount> membersAdded, TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    foreach (TeamsChannelAccount member in membersAdded)
    {
        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);
        }
    }
}

Team members removed

The teamMemberRemoved event is sent to your bot if it is removed from a team and every time any user is removed from a team that your bot is a member of. You can determine if the new member removed was the bot itself or a user by looking at the Activity object of the turnContext. If the Id field of the MembersRemoved object is the same as the Id field of the Recipient object, then the member removed is the bot, otherwise it is a user. The bot's Id will generally be: 28:<MicrosoftAppId>

[!Note] When a user is permanently deleted from a tenant, membersRemoved conversationUpdate event is triggered.

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 renamed

Your bot is notified when the team it is in has been renamed. It receives a conversationUpdate event with eventType.teamRenamed in the channelData object.

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

Message reaction events

The messageReaction event is sent when a user adds or removes reactions to a message which was sent by your bot. The replyToId contains the ID of the specific message, and the Type is the type of reaction in text format. The types of reactions include: "angry", "heart", "laugh", "like", "Sad", "surprised". This event does not contain the contents of the original message, so if processing reactions to your messages is important for your bot you'll need to store the messages when you send them.

EventType Payload object Description Scope
messageReaction reactionsAdded Reaction to bot message All
messageReaction reactionsRemoved Reaction removed from bot message All

Reactions to a bot message

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

Reactions removed from bot message

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