Add a chatbot to Microsoft Teams from within the Teams app

Select the version of Power Virtual Agents you're using here:

After you've built a bot, you'll want people to use it.

Now that you have published your bot, you can make your bot available to users in Microsoft Teams so you, your teammates, and the broader organization can interact with it. You need to publish the bot at least once before users can interact with the bot in Microsoft Teams.

You can:

  • Customize your bot's appearance in Microsoft Teams.
  • Install the bot for yourself in Microsoft Teams.
  • Share the bot's installation link with other users.
  • Show the bot in the Microsoft Teams app store.
    • Show the bot to your teammates or shared users by adding it to the Microsoft Teams app store Built by your colleagues section.
    • Show the bot with your organization by submitting the bot for admin approval to be featured in the Microsoft Teams app store Built by your org section.
  • Add the bot to a team channel.
  • Download the pre-generated Teams app manifest to distribute it within your Microsoft Teams tenant.

Prerequisites

Customize bot's appearance in Microsoft Teams

Providing the right description and appearance for the bot before making it available to other users is important, as it educates them on what the bot's purpose is and its branding (when applicable).

  1. In the navigation menu, select Publish and then select Make available to others.

  2. Select Edit details to change the bot's icon, color, and descriptions. These will be shown in the Microsoft Teams app store and the app's About tab after the user installs it. Review the recommendations on Microsoft Teams icon formats.

    You can make changes to the icon, background color, and descriptions.

    Important

    Updates to the bot's details will not apply to users who have already installed the bot from a shared link or the built by your colleague section. They will need to reinstall the bot to receive the updates.

    Updates to the bot's details will not apply to bots that have been approved by an admin. You will need to resubmit the bot for approval to have the latest details updated for users.

  3. Select More to add additional information:

    • Developer name
    • Website
    • Privacy Statement
    • Terms of use

    You should provide this information to keep your users informed about the bot. See the Privacy statement and terms of use topic for more details and examples.

  4. Select Save to return to the screen where you can make your bot available in Teams. You'll see your updates to the color, icon, and description are shown.

Note

Icon customization in this section only applies to the bot avatar for bots that are approved by admin and does not apply for users who install the bot with a direct installation link or from the Microsoft Teams app store Built by your colleague section.

You can customize the bot's avatar at Customize the look and feel of the bot.

Bot avatar icon in Teams chat.

Install a bot as an app in Microsoft Teams

After you have published a bot, you can add the bot to your own version of Microsoft Teams directly from the Power Virtual Agents app.

Important

New content in a freshly published bot won't appear in conversations that are currently ongoing. After 30 minutes of idle time, the bot will be updated.

You can type Start over in an existing conversation to start a new conversation right away and see the latest updates to the bot.

You should add your bot to your own version of Teams before sharing it with others.

  1. Go to the Chatbot tab.

    The chatbot tab is in the top pane.

  2. Open the bot you want to add.

  3. In the navigation menu, select Publish.

  4. Select Open the bot to have the installation prompt launch in Microsoft Teams. Select Add to have it added as an app in Teams. This only installs the bot for you.

    Open bot from Publish page.

  1. Go to the Chatbot tab.

  2. Open the bot you want to share.

  3. In the navigation menu, select Publish.

  4. Select Make the bot available to others.

    Make the bot available to others from Publish page

  5. Select Availability options and select Copy link.

    Important

    Only users who can access the bot can use the installation link to install the bot. You can share the bot to give user access to the chat with the bot.

    Copy link from Teams availability options.

  6. Share the copied link with users to install the bot in Microsoft Teams.

Show the bot in Microsoft Teams app store

Once you've published your bot, you can show it in the Microsoft Teams app store so users can find and install it.

Show to teammates and shared users

You can share your bot by adding it to the Microsoft Teams app store, Built for your org > Built by your colleagues section. Only your teammates and shared users will find the bot there.

Important

Only teammates or shared users can find and install the bot in the Microsoft Teams app store Built by your colleague section. The bot will not show for everyone in the organization even if it is configured to allow everyone to use the bot. To show the bot to the organization, submit the bot for admin's approval to show in Microsoft Teams app store Built by your org section.

The bot can only be shown in the Microsoft Teams app store Built by your colleague section when the total number of shared users does not exceed the tenant's Teams app store discovery policy. To show the bot beyond your organization's policy limit, partner with your admin to show the bot to the organization.

The Built by your colleagues section as at the bottom of the Built for your org section in the Teams app store.

  1. Go to the Chatbot tab.

  2. Open the bot you want to show in the Microsoft Teams app store.

  3. In the navigation menu, select Publish.

  4. Select Make the bot available to others.

  5. Select Availability options.

  6. Select Show to my teammates and shared users and review who has access to the bot.

    Show bot in Teams app store Built by your colleague section.

  7. Confirm that Visible in Built by your colleagues is selected and select Share.

    Select visible in Built by your colleagues checkbox in sharing UI.

  8. This will automatically add the bot to the Built by your colleagues section, and will show a green label Added to Teams in the availability options page.

The flyout shows the bot has been added to Teams.

Note

If your app doesn't appear in the Built by your colleagues section, your Teams app might be caching information.

Try signing out and back in again (if you're using the desktop app) or refreshing your browser (if you're using the web app of Teams).

Remove the bot from the Built by your colleagues section

You can remove the bot from showing in the Built by your colleagues section. This does not impact users who have already installed the bot.

  1. Go to the Chatbot tab.

  2. Open the bot you want to remove.

  3. In the navigation menu, select Publish.

  4. Select Make the bot available to others.

  5. Select Availability options.

  6. Select Show to my teammates and shared users and remove Visible in Built by your colleagues checkbox selection.

    Uncheck visible in Built by your colleagues checkbox in sharing UI.

  7. Select Share. Now the bot will no longer show in Microsoft Teams app store Built by your colleague section.

Show to the organization

You can share the bot with your organization by submitting your bot for admin approval to be featured in the Built for your org > Built by your colleagues section. This is a great way to broadly distribute your bot by partnering with your admin to roll out the bot to everyone in the organization, or a subset of users.

The Built by your org section is at the top of the Built for Org section in the Teams app store.

Admins can also preinstall and pin the bot for users in the organization so they can access it directly from their left app bar in Microsoft Teams.

Before submitting the bot to your organization, make sure:

  • Your bot is ready for release and in compliance with company standards, rules and policies.
  • You coordinate with your teammates: once the bot has been submitted it can't be re-submitted by a different user until the previous submission is approved or rejected by an admin.
  • You have removed the bot, if applicable, from the Built by your colleagues section. Submitting your bot for admin approval could result in your bot showing up in two places. See the instructions on removing your bot for details.

Note

Once a bot is approved by an admin, the bot availability in the Built by your org section will be completely managed by your admin. Only an admin can remove the bot from the Built by your org section.

Submit for the Built by your org section

  1. Go to the Chatbot tab.

  2. Open the bot you want to submit.

  3. In the navigation menu, select Publish.

  4. Select Make the bot available to others.

  5. Select Availability options.

  6. Confirm the bot is not shown to teammates or shared users. Remove it if it says Added to Teams.

  7. Select Show to everyone in my org.

    Show bot to organization in Teams pane availability options.

  8. Review the requirements for submission, and select Submit for admin approval.

    Note

    Make sure you review the content when it's ready for an admin to review. You will need to submit new requests to the admin to update the icon and descriptions for bots that were previously approved.

    Once approved, all new and existing users of the bot in Teams will receive the update.

    This only applies to the bot details. You can continue to make content updates to your bot by publishing the latest content without needing to re-submit to admin.

  9. A final confirmation prompt will appear. Select Yes to continue. The bot will be sent to your admin for them to approve it, and you will see a note indicating the status of your submission.

    The status has an orange note with information about the status of the submission, including the name of the bot, the version number, and the current status Waiting for approval

    Note

    After submitting the bot for admin approval, you should not change the bot's access setting to be less than everyone in your organization.

    This will result in users in the organization unable to chat with the bot after installing it from the Microsoft Teams app store Built by your org section.

    Work with your admin and the Microsoft Teams app policy on who can find and install the bot.

  10. You will need to wait for your admin's approval. You can check the latest status by selecting Refresh, or opening the Make the bot available to others window from the Publish page.

  11. After your admin approves the bot, the status will be updated to Approved. You can directly open the bot and share the approved version's link with other users.

  12. Optionally, partner with your admin to pre-pin or install the app for users with the Microsoft Teams app policy so they can find the bot directly in their Microsoft Teams app list.

Note

If your app doesn't appear in the Built by your org section even though it's marked as Approved, your Teams app might be caching information.

Try signing out and back in again (if you're using the desktop app) or refreshing your browser (if you're using the Teams web app).

Add a bot to a team

Microsoft Teams supports adding bots to teams. Once added, team members can @mention the bot in any team channels and all teammates will see the response from the bot. This feature is useful for scenarios where:

  • Your bot supports collaboration, for example sharing the latest sales report insight with the rest of the Sales team.
  • You want to allow every team member to engage with the bot in a team channel or via private chat without needing to manually install the bot themselves.

You can add the bot directly into the team that the bot is created in or allow users to add the bot to any team that they're part of. Team members can also remove the bot from the team.

Add bot to the team it is created in

When you create a bot, you need to select a team for the bot to be created in. You can directly add the bot to this team so members of the team can interact with it.

To add a bot to the team it was created in:

  1. Go to the Chatbot tab.

  2. Open the bot you want to add to the team.

  3. In the navigation menu, select Publish.

  4. Select Make the bot available to others.

  5. Select Availability options.

  6. Select Add to {team name}.

    The UI has a button to let maker add bot to the team the bot is created in

  7. Select Add to add the bot to the team.

Allow users to add bot to their teams

This option allows users to add the bot to any team that they're part of when adding the bot in Microsoft Teams.

After enabling this option, any user who installs the bot from the Teams app store or via the installation link will see the option to add the bot to a team in Microsoft Teams. Team members can also remove the bot from a team.

Important

The bot will be configured to allow everyone in the organization to chat with it. This ensures all team members have permission to chat with the bot in team channels. It's highly recommended to not change the security setting of the bot after enabling this capability to prevent users seeing permission errors when interacting with the bot in team channels.

To allow users to add a bot to a team:

  1. Go to the Chatbot tab.

  2. Open the bot you want to allow users to add to any team.

  3. In the navigation menu, select Publish.

  4. Select Make the bot available to others.

  5. Select Edit details.

  6. Select Allow your users to add this bot to a team.

    Checkbox is checked to allow user to add bot to teams that they are part of

  7. Select Save.

Microsoft Teams caches information so it could take a while before users see the option to add the bot to a team. Users can refresh the browser or sign in and out of the Microsoft Teams desktop client to reflect changes immediately.

If you've previously submitted the bot for admin approval, you'll need to resubmit after enabling this option. The admin needs to approve these changes before users can add the bot to their teams from Microsoft Teams app store in the "Built by your org" section.

Disallow users from adding bot to a team

Disabling this option will prevent users from adding a bot to a new team, but won't remove it from teams that it's already added to. Those bots will need to be manually removed from the team.

To disallow users from adding a bot to a team:

  1. Go to the Chatbot tab.

  2. Open the bot you want to disallow users to add to any team.

  3. In the navigation menu, select Publish.

  4. Select Make the bot available to others.

  5. Select Edit details.

  6. Clear the Allow your users to add this bot to a team checkbox.

    Checkbox is unchecked to disallow user to add bot to teams that they are part of

  7. Select Save.

Configure private greeting behavior

Private greetings from a bot are useful for when you want team members to have one-on-one conversations with the bot without needing to manually install the bot themselves.

When enabled, your bot will automatically start a conversation with team members. To customize the bot's greeting message, modify the Greeting system topic.

Consider how relevant the bot is to team members. Make sure the bot's greeting helps them understand what to do with it, describes its limitations and, most importantly, gets them comfortable interacting with it.

To configure a when a bot sends a private greeting:

  1. Go to the Chatbot tab.

  2. Open the bot you want to modify.

  3. In the navigation menu, select Publish.

  4. Select Make the bot available to others.

  5. Select Settings.

    Settings entry point to configure bot's private greeting behavior

  6. Configure the private greeting options.

    Private greeting to user setting options

  7. Select Save.

Download the bot's Teams app manifest (advanced)

You can download the bot's Teams app manifest to make detail changes to the manifest directly and share with your admin or users in the tenant. You can also directly upload the app manifest into Microsoft Teams if your organization's policy allows you to upload custom applications.

  1. Go to the Chatbot tab.

  2. Open the bot you want to download.

  3. In the navigation menu, select Publish.

  4. Select Make the bot available to others.

  5. Select Availability options.

  6. Select Download .zip.

    Download Teams app manifest zip file from Teams pane availability options.

  7. The manifest will be generated as a .zip file, and will be saved according to your browser's save settings.

Uninstall the bot from the side bar

You can remove the bot from your list of apps if you no longer want to use it. This doesn't delete the bot from the Power Virtual Agents app, it just means you can't chat with the bot in Microsoft Teams.

  1. Right-click the bot's app icon.

  2. Select Uninstall and then select Uninstall.

    Uninstall the bot.

Disconnect your bot from Teams

You can take your bot offline so users can no longer chat with the bot in Teams. This means the bot won't respond to anyone who tries to chat with it, and will disrupt anyone who is using the bot. You should thoroughly consider the need to disconnect your bot before you do so.

Bots no longer show in the Microsoft Teams app store Built by your colleague section, and they can't be installed from a shared link. Bots that are added by users in Microsoft Teams will continue to exist until the user uninstalls the bot.

For bots that are approved by an admin, the bots will continue to be shown in the Microsoft Teams app store Built by your org section. You will need to contact your admin to remove the bot.

  1. Go to the Chatbot tab.

  2. Open the bot you want to disconnect.

  3. In the navigation menu, select Publish.

  4. Select Make the bot available to others.

  5. Select Disconnect from Teams.

    Disconnect Teams channel in Teams channel pane.

  6. Review the information about disconnecting your bot, and select Disconnect to continue.

You can always reconnect your bot after disconnecting it by selecting Turn on Teams in the Make the bot available to others window on the Publish page.

Known limitations

  • Currently, only the Personal and Team scopes are supported for Microsoft Teams. Group chat is not supported.
  • Setting the bot avatar icon on the details page won't show up for bots that are approved by an admin. Bots approved by an admin will use the app icon as the bot avatar.
  • Teams has rate limiting on bots. Depending on your business needs, you might want to keep your bot content concise for bots that are added to Microsoft Teams.
  • Disconnecting your bot might take a few minutes before the bot becomes unreachable by users on Microsoft Teams.