Have a conversation with a Microsoft Teams bot

03/02/2018

10 minutes to read

Contributors

In this article

A conversation is a series of messages sent between your bot and one or more users. Bots in Microsoft Teams allow sending messages in either personal conversations with a single user (also known as one-on-one or 1:1 chats) or a group conversation in a Teams channel.

Note

Bots in private group chats are currently not supported.

Conversation basics

Each message is an Activity object. When a user sends a message, the channel on which she or he is communicating posts the message to your bot (web service). 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).

Your bot can send rich text, pictures, and cards. Users can send rich text and pictures to your bot. You can specify the type of content your bot can handle in the Microsoft Teams settings page for your bot.

Picture messages

Pictures can be at most 1024×1024 and 1 MB in PNG, JPEG, or GIF format; animated GIF is not officially 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)

Receiving messages

Depending on which scopes are declared, your bot can receive messages in the following contexts:

1:1 chat Users can interact in a private conversation with a bot by simply selecting the added bot in the chat history, or typing its name or app ID in the To: box on a new chat.

Channels A bot can be mentioned ("@botname") in a channel if it has been added to the team. Note that additional replies to a bot in a channel require mentioning the bot—it will not respond to replies where it is not mentioned.

For incoming messages, your bot receives an Activity object of type message. Altough the Activity object can contain other types of information, like channel updates sent to your bot, the message type represents communication between bot and user.

Your bot receives a payload that contains the user message Text as well as other information about the user, the source of the message, and Teams information. Of note:

timestamp The date and time of the message in Coordinated Universal Time (UTC)

localTimestamp The date and time of the message in the time zone of the sender

channelId Always "msteams"

from.id A unique and encrypted ID for that user for your bot; suitable as a key if your app needs to store user data

channelData.tenant.id The tenant ID for the user.

Note

from.id is unique for your bot and cannot be directly used outside your bot instance in any meaningful way to identify that user.

The message content itself can contain simple text or some of the Bot Framework–supplied cards and card actions.

Please note that in your outbound schema you should always use the same serviceUrl as the one you received. Be aware that the value of serviceUrl tends to be stable but can change. When a new message arrives, your bot should verify its stored value of serviceUrl.

Updating messages

Rather than have your messages be static snapshots of data, your bot can now dynamically update messages inline after sending them to users. You can use dynamic message updates for scenarios such as poll updates, modifying available actions after a button press, or any other asynchronous state change.

The new message need not match the original in type. For instance, if the original message contained an attachment, the new message can be a simple text message.

Note

Currently, you can update only content sent in single-attachment messages and carousel layouts. Posting updates to messages with multiple attachments in list layout will be supported soon.

REST API

To issue a message update, simply perform a PUT request against the /v3/conversations/<conversationId>/activities/<activityId>/ endpoint using a given activity ID. To complete this scenario, you should cache the activity ID returned by the original POST call.

Creating a conversation

You can create a 1:1 conversation with a user or start a new reply chain in a channel for your team bot. This lets you to message your user or users without having them first initiate contact with your bot. For more information, see the following topics:

The feedback system for this content will be changing soon. Old comments will not be carried over. If content within a comment thread is important to you, please save a copy. For more information on the upcoming change, we invite you to read our blog post.