Designing your Microsoft Teams bot
Bots are conversational apps that perform a specific set of tasks. Based on the Microsoft Bot Framework, bots communicate with users, respond to their questions, and proactively notify them about changes and other events. They're a great way to reach out.
Important
Bots are available in Government Community Cloud (GCC), GCC-High, and Department of Defense (DOD) environments.
To guide your app design, the following information describes and illustrates how people can add, use, and manage bots in Teams.
You can find more comprehensive bot design guidelines, including elements that you can grab and modify as needed, in the Microsoft Teams UI Kit.
Bots are available in chats, channels, and personal apps.
Users can access bots that were added on desktop with an @mention.
Users can add a bot one of the following ways:
From the Microsoft Teams Store.
Using the app flyout by selecting the More icon on the left side of Teams.
With an @mention in the new chat or compose box (the following example shows how you can do this in a group chat).
It’s critical that your bot introduces itself and describes what it can do. This initial exchange helps people understand what to do with the bot, find out its limitations and, most importantly, get comfortable interacting with it.
In personal contexts, welcome messages set your bot's tone. The message includes a greeting, what the bot can do, and some suggestions for how to interact. For example, “Try asking me about …”. If possible, these suggestions should return stored responses without having to sign in.
Your bot's introduction should be slightly different in channels and group chats compared to a personal space (like a personal app). In real life, if you entered a room full of people; you’d introduce yourself instead of welcoming everyone who’s already there. Carry that thinking into your bot design.
When a person messages a bot, sign in may be required use all its features. You can simplify the authentication process using single sign-on (SSO).
Don’t forget: In the bot command menu (What can I do?), you must also provide a command to sign out.
You can include a tour with welcome messages and if the bot responds to something like a “help” command. A tour is the most effective way to describe what your bot can do. If applicable, they’re also great for describing your app’s other features. For example, include screenshots of your message extension.
Important
Tours should be accessible without having to sign in.
In a personal app, a carousel can provide an effective overview of your bot and any other features of your app. Including buttons the let users try bot commands is encouraged. For example, Create a task.
In channels and group chats, a tour should open in a modal (also known as a dialogs (referred as task modules in TeamsJS v1.x)) so it doesn’t interrupt ongoing conversations. This also gives you the option to implement role-based views for your tour.
Bots integrate directly into Team’s messaging framework. Users can chat with a bot to get their questions answered or type commands to have the bot perform a narrow or specific set of tasks. Bots can proactively notify users about changes or updates to your app through chat.
You can use bots in the following contexts:
- Personal apps: In a personal app, a bot has a dedicated chat tab.
- One-on-one chat: A user can initiate a private conversation with a bot. It's the same experience as using a bot in a personal app.
- Group chat: People can interact with a bot in a group chat by @mentioning the bot.
- Channel: People can interact with a bot in a channel. by @mentioning the bot name in the compose box. Remember, in this context, the bot is available to the entire team, not just the channel.
Counter | Description |
---|---|
1 | App name and icon |
2 | Chat tab: Opens the space to talk with your bot (applicable only to personal apps). |
3 | Custom tabs: Opens other content related to your app. |
4 | About tab: Displays basic information about your app. |
5 | Chat bubble: Bot conversations use the Teams messaging framework. |
6 | Adaptive Card: If your bot's responses include Adaptive Cards, the card takes up the full width of the chat bubble. |
Counter | Description |
---|---|
1 | App name and icon |
2 | Chat tab: Opens the space to talk with your bot (applicable only to personal apps). |
3 | Custom tabs: Opens other content related to your app. |
4 | About tab: Displays basic information about your app. |
5 | Chat bubble: Bot conversations use the Teams messaging framework. |
6 | Adaptive Card: If your bot's responses include Adaptive Cards, the card takes up the full width of the chat bubble. |
7 | Command menu: Displays your bot's standard commands (defined by you). |
The command menu provides a list of words or phrases you want your bot to always respond to. The command menu displays above the compose box when someone is conversing with a bot. When a command is selected, it gets inserted into a message.
The list of commands should be brief. The menu is only meant to highlight your bot’s primary features. Keep commands concise, too. For example, create a command called Help instead of Can you please help me?
The command menu must always be available regardless of the state of the conversation.
Use a thesaurus and get people from as many different backgrounds as possible to help you generate different interpretations of standard queries.
Design your bot to recognize intent, which captures what someone wants from a bot in response to a message or query. Intent classifies a message or query as a single action with one or more data objects that are affected by the action.
The following examples outline the user intent and data in messages sent to bots:
Learn what users say when chatting with your bot. This will be an ongoing, iterative process as your user base grows in different locations and orgs. You can tune your bot's language recognition and intent mapping with Microsoft Language Understanding (LUIS).
- Understanding LUIS: Find out how LUIS uses AI to provide natural language understanding (NLU) to your app data.
- Integrating with LUIS: Add natural language capabilities to your bot without the complex process of creating machine learning models.
Bots can deliver an exact match to a query or a group of related matches to help with disambiguation. For related matches, group the content using a list card.
While your bot can support complete requests and questions, it should also be able to handle multi-turn interactions. Anticipating possible next steps makes it much easier for people to a complete task flow (rather than expecting them to craft a comprehensive request).
In the following examples, the bot responds to each message with options for what might want to do next.
With proactive messaging, your bot can act like a digest that sends notifications relevant to an individual, group chat, or channel at a specific frequency. A bot may send a message when something has changed in a document or a work item is closed.
In the following example, the user gets a notification that a bot messaged them in another channel.
Now in that channel, the user can read their message from the bot.
In the following example, the user gets a toast notification that a bot messaged them in another channel.
Now in that channel, the user can read their message from the bot.
In personal apps, a tab can complement what your bot can do. For example, if your bot can create work items, it's nice to show all those items in a central location inside a tab. See more about designing tabs.
Users should be able to change a bot's settings. You can provide this functionality with bot commands, but it's usually more efficient to include all settings in a dialog (as shown in the following example).
Use these recommendations to create a quality app experience.
Is your bot's tone friendly and light, “just the facts”, or super quirky? How should it respond in different scenarios? Planning and documenting your bot's persona makes it easier to write responses that seem natural and cohesive.
See more about writing for bots in the Microsoft Teams UI Kit (Figma).
Do: Clearly convey what your bot can do
Welcome messages and tours help people understand what they can do with your bot.
Don't: Obscure your bot's features
First impressions matter. People will likely be confused or suspicious when presented with a nondescript sign-in message.
Do: Recognize non-questions
Your bot should be able to respond to messages like "Hi", "Help", and "Thanks" while also accounting for common misspellings and colloquialisms.
Don't: Miss out on opportunities to delight
Some people expect conversations to flow naturally like they would with a real person. Try to avoid clumsy responses to simple messages.
Do: Provide help
If your bot can’t satisfy a request, provide ways for a user to educate themselves about interacting with your bot.
Don't: Leave users stranded
People will quickly abandon your bot if they can’t troubleshoot issues.
Do: Use dialogs or tabs
If your bot provides an answer that requires a few more steps, you can link to a modal dialog or tab to complete the task or flow.
Don't: Make multi-turn interactions tedious
An extensive conversation to complete a single task is slow and overly complex. It also requires the developer to account for state changes (such as the conversation timing out or you sending a “Cancel” message).
Do: Only show sensitive info in a personal context
If your bot is in a group chat or channel, we recommend directing users to a private location (such as a modal dialog, tab, or browser) to view sensitive information.
Don't: Some content isn’t meant to be seen by everyone
Your bot shouldn’t reveal sensitive information to a group of people.
These other guidelines may help with your bot design:
Platform Docs feedback
Platform Docs is an open source project. Select a link to provide feedback: