Channel and group chat conversations with a bot

Important

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

To install the Microsoft Teams bot in a team or group chat, add the teams or groupchat scope to your bot. This allows all members of the conversation to interact with your bot. After the bot is installed, it has access to metadata about the conversation, such as the list of conversation members. Also, when it is installed in a team, the bot has access to details about that team and the full list of channels.

Bots in a group or channel only receive messages when they are mentioned @botname. They do not receive any other messages sent to the conversation.

Note

The bot must be @mentioned directly. Your bot does not receive a message when the team or channel is mentioned, or when someone replies to a message from your bot without @mentioning it.

Design guidelines

Unlike personal chats, in group chats and channels, your bot must provide a quick introduction. You must follow these and more bot design guidelines. For more information on how to design bots in Teams, see how to design bot conversations in channels and chats.

Now, you can create new conversation threads and easily manage different conversations in channels.

Create new conversation threads

When your bot is installed in a team, you must create a new conversation thread rather than reply to an existing one. At times it is difficult to differentiate between two conversations. If the conversation is threaded, it is easier to organize and manage different conversations in channels. This is a form of proactive messaging.

Next, you can retrieve mentions using the entities object and add mentions to your messages using the Mention object.

Work with mentions

Every message to your bot from a group or channel contains an @mention with its name in the message text. Ensure that your message parsing handles @mention. Your bot can also retrieve other users mentioned in a message and add mentions to any messages it sends.

You must also strip out the @mentions from the content of the message your bot receives.

Retrieve mentions

Mentions are returned in the entities object in payload and contain both the unique ID of the user and the name of the user mentioned. The text of the message also includes the mention, such as <at>@John Smith<at>. However, do not rely on the text in the message to retrieve any information about the user. It is possible for the person sending the message to alter it. Therefore, use the entities object.

You can retrieve all mentions in the message by calling the GetMentions function in the Bot Builder SDK, which returns an array of Mention objects.

The following code shows an example of retrieving mentions:

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    Mention[] mentions = turnContext.Activity.GetMentions();
    if(mentions != null)
    {
        ChannelAccount firstMention = mentions[0].Mentioned;
        await turnContext.SendActivityAsync($"Hello {firstMention.Name}");
    }
    else
    {
        await turnContext.SendActivityAsync("Aw, no one was mentioned.");
    }
}

Add mentions to your messages

Your bot can mention other users in messages posted into channels.

The Mention object has two properties that you must set using the following:

  • Include @username in the message text.
  • Include the mention object inside the entities collection.

The Bot Framework SDK provides helper methods and objects to create mentions.

The following code shows an example of adding mentions to your messages:

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    var mention = new Mention
    {
        Mentioned = turnContext.Activity.From,
        Text = $"<at>{XmlConvert.EncodeName(turnContext.Activity.From.Name)}</at>",
    };

    var replyActivity = MessageFactory.Text($"Hello {mention.Text}.");
    replyActivity.Entities = new List<Entity> { mention };

    await turnContext.SendActivityAsync(replyActivity, cancellationToken);
}

Now you can send an introduction message when your bot is first installed or added to a group or team.

Send a message on installation

When your bot is first added to the group or team, an introduction message must be sent. The message must provide a brief description of the bot's features and how to use them. You must subscribe to the conversationUpdate event with the teamMemberAdded eventType. The event is sent when any new team member is added. Check if the new member added is the bot. For more information, see sending a welcome message to a new team member.

Send a personal message to each team member when the bot is added. To do this, get the team roster and send each user a direct message.

Do not send a message in the following cases:

  • The team is large, for example, larger than 100 members. Your bot can be seen as spam and the person who added it can get complaints. You must clearly communicate your bot's value proposition to everyone who sees the welcome message.
  • Your bot is first mentioned in a group or channel instead of being first added to a team.
  • A group or channel is renamed.
  • A team member is added to a group or channel.

Teams bot samples

Code sample

For complete working samples demonstrating the functionality, see the following Teams samples for Bot Framework:

Sample Description .NET JavaScript Python
Teams conversation bot Messaging and conversation event handling. View View View
Authentication with OAuthPrompt Authentication and basic messaging in Bot Framework v4. View View View
Teams file upload Exchanging files with a bot in a one-to-one conversation. View View View
Task module Retrieving a task module and values from cards in it for a messaging extension. View View View
Start new thread in a channel Creating a new thread in a channel. View View View

See also

Get Teams context

Next step