Conversation basics

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.

A conversation is a series of messages sent between your bot and one or more users. There are three kinds of conversations (also called scopes) in Teams:

  • teams Also called channel conversations, visible to all members of the channel.
  • personal Conversations between bots and a single user.
  • groupChat Chat between a bot and two or more users. Also enables your bot in meeting chats.

A bot behaves slightly differently depending on what kind of conversation it is involved in:

  • Bots in channel and group chat conversations require the user to @ mention the bot to invoke it in a channel.
  • Bots in a one-to-one conversation do not require an @ mention. All messages sent by the user will be routed to your bot.

To enable your bot in a particular scope, add that scope to your app manifest.

Activities

Each message is an Activity object of type messageType: message. When a user sends a message, Teams posts the message to your bot; specifically, it sends a JSON object to your bot's messaging endpoint. Your bot examines the message to determine its type and responds accordingly.

Basic conversation is handled through the Bot Framework Connector, a single REST API to enable your bot to communicate with Teams and other channels. The Bot Builder SDK provides easy access to this API, additional functionality to manage conversation flow and state, and simple ways to incorporate cognitive services such as natural language processing (NLP).

Receive a message

To receive a text message, use the Text property of the Activity object. In the bot's activity handler, use the turn context object's Activity to read a single message request.

The code below shows an example.

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
  await turnContext.SendActivityAsync(MessageFactory.Text($"Echo: {turnContext.Activity.Text}"), cancellationToken);
}

Send a message

To send a text message, specify the string you want to send as the activity. In the bot's activity handlers, use the turn context object's SendActivityAsync method to send a single message response. You can also use the object's SendActivitiesAsync method to send multiple responses at once. The code below shows an example of sending a message when someone is added to a conversation

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
  await turnContext.SendActivityAsync(MessageFactory.Text($"Hello and welcome!"), cancellationToken);
}

Teams channel data

The channelData object contains Teams-specific information and is the definitive source for team and channel IDs. You may need to cache and use these ids as keys for local storage. The TeamsActivityHandler in the SDK will typically pull out important information from the channelData object to make it more easily accessible, however you can always access the original information from the turnContext object.

The channelData object is not included in messages in personal conversations since these take place outside of any channel.

A typical channelData object in an activity sent to your bot contains the following information:

  • eventType Teams event type; passed only in cases of channel modification events
  • tenant.id Azure Active Directory tenant ID; passed in all contexts
  • team Passed only in channel contexts, not in personal chat.
    • id GUID for the channel
    • name Name of the team; passed only in cases of team rename events
  • channel Passed only in channel contexts when the bot is mentioned or for events in channels in teams where the bot has been added
  • channelData.teamsTeamId Deprecated. This property is included only for backwards compatibility.
  • channelData.teamsChannelId Deprecated. This property is included only for backwards compatibility.

Example channelData object (channelCreated event)

"channelData": {
    "eventType": "channelCreated",
    "tenant": {
        "id": "72f988bf-86f1-41af-91ab-2d7cd011db47"
    },
    "channel": {
        "id": "19:693ecdb923ac4458a5c23661b505fc84@thread.skype",
        "name": "My New Channel"
    },
    "team": {
        "id": "19:693ecdb923ac4458a5c23661b505fc84@thread.skype"
    }
}

Message content

Your bot can send rich text, pictures, and cards. Users can send rich text and pictures to your bot.

Format From user to bot From bot to user Notes
Rich text
Pictures Maximum 1024×1024 and 1 MB in PNG, JPEG, or GIF format; animated GIF are not supported
Cards See the Teams Card Reference for supported cards
Emojis Teams currently supports emojis via UTF-16 (such as U+1F600 for grinning face)

Adding notifications to your message

Notifications alert users about new tasks, mentions and comments related to what they are working on, or need to look at by inserting a notice into their Activity Feed. You can set notifications to trigger from your bot message by setting the TeamsChannelData objects Notification.Alert property to true. Whether or not a notification is raised will ultimately depend on the individual user's Teams settings and you cannot programmatically override these settings. The type of notification will be either a banner or both a banner and an email.

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
  var message = MessageFactory.Text("You'll get a notification, if you've turned them on.");
  message.TeamsNotifyUser();

  await turnContext.SendActivityAsync(message);
}

Picture messages

Pictures are sent by adding attachments to a message. You can find more information on attachments in the Bot Framework documentation.

Pictures can be at most 1024×1024 and 1 MB in PNG, JPEG, or GIF format; animated GIF is not supported.

We recommend that you specify the height and width of each image by using XML. If you use Markdown, the image size defaults to 256×256. For example:

  • Use - <img src="http://aka.ms/Fo983c" alt="Duck on a rock" height="150" width="223"></img>
  • Don't use - ![Duck on a rock](http://aka.ms/Fo983c)

Next steps