Create a bot for Microsoft Teams

You'll need to complete the following steps to create a conversational bot.

  1. Prepare your development environment.
  2. Create your web service.
  3. Register your web service as a bot with the Bot Framework.
  4. Create your app manifest, and your app package
  5. Upload your package to Microsoft Teams

Creating your web service, creating your app package, and registering your web service with the Bot Framework can be done in any order. Because those three pieces are so intertwined, no matter which order you do them in you'll need return to update the others. Your registration needs the messaging endpoint from your deployed web service, and your web service needs the ID and password created from your registration. You app manifest also needs that Id to connect Teams to your web service.

As you're building your messaging extension, you'll regularly be moving between changing your app manifest, and deploying code to your web service. When working with the app manifest, keep in mind that you can either manually manipulate the JSON file, or make changes through App Studio. Either way, you'll need to re-deploy (upload) your app in Teams when you make a change to the manifest, but there's no need to do so when you deploy changes to your web service.

See the Bot Framework Documentation for additional information on the Bot Framework.

Prepare your development environment

The first thing you'll need to do is prepare your development environment. You'll need to make sure custom app uploading is enabled for the Office 365 organization you want to build your app in. If you need a dedicated development tenant, you can sign up for the Office 365 developer program. For additional information see Setup your development environment.

Create your web service

The heart of your bot is your web service. It will define a single route, typically /api/messages, to receive all requests on. If you're getting started from scratch, you have a few options to choose from.

  • Use one of our quickstarts tutorials that will guide you through the creation of your web service.
  • Start with the Teams conversation bot sample in either C#/dotnet or JavaScript.
  • If you're using JavaScript, use the Yeoman generator for Microsoft Teams to scaffold your Teams app, including your web service.
  • Create your web service from scratch. You can choose to add the Bot Framework SDK for your language, or you can work directly with the JSON payloads.

Register your web service with the Bot Framework

Important

When registering your web service, be sure to set the Display name to the same name you use for your Short name in your app manifest. When your app is distributed by either direct uploading or through the organizational app catalog messages sent to a conversation by your bot will use the registration's Display name rather than the app's Short name.

Registering your web service with the Bot Framework provides a secure communication channel between the Teams client and your web service. The Teams client and your web service never communicate directly. Instead, messages are routed through the Bot Framework Service (Microsoft Teams uses a separate instance of this service that is compliant with the Office 365 standards).

If you do not wish to create your bot registration in Azure, you must use either this link - https://dev.botframework.com/bots/new, or App Studio. If you click on the Create a bot button in the Bot Framework portal, you will create your bot registration in Microsoft Azure instead. To manage or migrate your registration after creation go to: https://dev.botframework.com/bots.

When you edit the properties of an existing registration that is not registered in Azure, such as its "messaging endpoint," you will see "Migration status" column and a blue "Migrate" button that will take you into the Microsoft Azure portal. Don't click on the "Migrate" button unless that's what you want to do; instead, click on the name of the bot and you can edit its properties:

Edit Bot Properties

Scenarios when you must have your bot registration in Azure (either by creating it in the Azure portal or migrating):

  • You want to use the Bot Framework's OAuthPrompt for authentication.
  • You want to enable additional channels like webchat, Direct Line, or Skype.

Using App Studio

App Studio is an app in Teams that helps with registering your web service as a bot, and creating an app package that references your bot. It also contains a React control library and configurable samples for cards. See Getting started with Teams App Studio.

Remember, if you use App Studio to register your web service you'll need to go to https://dev.botframework.com/bots to manage your registration. Some settings (like your messaging endpoint) can be updated in App Studio as well.

In the legacy portal

Create your bot registration using this link: https://dev.botframework.com/bots/new. Be sure to add Microsoft Teams as a channel from the featured channels list after creating your bot. Feel free to re-use any Microsoft App ID you generated if you've already created your app package/manifest.

Bot Framework registration page

With Azure

You can also register your web service by creating a Bot Channels Registration resource in the Azure portal.

  1. In the [Azure portal][azure-portal], on the left navigation panel, select Create a resource.

  2. In the right panel selection box enter "bot". And in the drop-down list, select Bot Channels Registration.

  3. Click the Create button.

  4. In the Bot Channel Registration blade, provide the requested information about your bot.

  5. Leave the Messaging endpoint box empty for now, you will enter the required URL after deploying the bot. The following picture shows an example of the registration settings:

    bot app channels registration

  6. Click Microsoft App ID and password and then Create New.

  7. Click Create App ID in the App Registration Portal link.

  8. In the displayed App registration window, click the New registration tab in the upper left.

  9. Enter the name of the bot application you are registering, we used BotTeamsAuth (you need to select your own unique name).

  10. For the Supported account types select Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox).

  11. Click the Register button. Once completed, Azure displays the Overview page for the application.

  12. Copy and save to a file the Application (client) ID value.

  13. In the left panel, click Certificate and secrets.

    1. Under Client secrets, click New client secret.
    2. Add a description to identify this secret from others you might need to create for this app.
    3. Set Expires to your selection.
    4. Click Add.
    5. Copy the client secret and save it to a file.
  14. Go back to the Bot Channel Registration window and copy the App ID and the Client secret in the Microsoft App ID and Password boxes, respectively.

  15. Click OK.

  16. Finally, click Create.

The Bot Framework portal is optimized for registering bots in Microsoft Azure. Here are some things to know:

  • The Microsoft Teams channel for bots registered on Azure is free. Messages sent over the Teams channel will NOT count towards the consumed messages for the bot.
  • If you register your bot using Microsoft Azure, your bot code does not need to be hosted on Microsoft Azure.
  • If you do register a bot using Microsoft Azure portal, you must have a Microsoft Azure account. You can create one for free. To verify your identity when you create one, you must provide a credit card, but it won't be charged; it's always free to create and use bots with Microsoft Teams.

Add your bot to your app manifest

Your app manifest defines the metadata for your app, the extensibility points your app use, and pointers to your web services. You can either use App Studio to help you create your app manifest, or create it manually.

Using App Studio

  1. In the Teams client, open App Studio from the ... overflow menu on the left navigation rail. If it isn't already installed, you can do so by searching for it.
  2. On the Manifest editor tab select Create a new app (or if you're adding a bot to an existing app, you can import your app package)
  3. Add your app details (see manifest schema definition for full descriptions of each field).
  4. On the Bots tab click the Setup button.
  5. You can either create a new web service registration (bot), or if you've already registered one select/add it here.
  6. Select the capabilities and scopes your bot will need.
  7. If necessary, update your bot endpoint address to point to your bot. It should look something like https://someplace.com/api/messages.
  8. Optionally, add bot commands.

Create it manually

As with messaging extensions and tabs, you update the app-manifest define your bot. Add new top-level JSON structure in your app manifest with the bots property.

Name Type Maximum size Required Description
botId String 64 characters The unique Microsoft app ID for the bot as registered with the Bot Framework. This may well be the same as the overall app ID.
needsChannelSelector Boolean Describes whether or not the bot utilizes a user hint to add the bot to a specific channel. Default: false
isNotificationOnly Boolean Indicates whether a bot is a one-way, notification-only bot, as opposed to a conversational bot. Default: false
supportsFiles Boolean Indicates whether the bot supports the ability to upload/download files in personal chat. Default: false
scopes Array of enum 3 Specifies whether the bot offers an experience in the context of a channel in a team, in a group chat (groupchat), or an experience scoped to an individual user alone (personal). These options are non-exclusive.

Optionally, you can define one or more list of commands that your bot can recommend to users. The object is an array (maximum of 2 elements) with all elements of type object; you must define a separate command list for each scope that your bot supports. See Bot menus for more information.

Name Type Maximum size Required Description
items.scopes array of enum 3 Specifies the scope for which the command list is valid. Options are team, personal, and groupchat.
items.commands array of objects 10 An array of commands the bot supports:
title: the bot command name (string, 32)
description: a simple description or example of the command syntax and its argument (string, 128)

Simple manifest example

The example below is a simple bot object, with two command lists defined. This is not the entire app manifest file, just the part specific to messaging extensions.

...
  "bots": [
    {
      "botId": "%MICROSOFT-APP-ID-REGISTERED-WITH-BOT-FRAMEWORK%",
      "needsChannelSelector": false,
      "isNotificationOnly": false,
      "scopes": [ "team", "personal", "groupchat" ],
      "supportsFiles": true,
      "commandLists": [
        {
          "scopes": [ "team", "groupchat" ],
          "commands": [
            {
              "title": "Command 1",
              "description": "Description of Command 1"
            },
            {
              "title": "Command N",
              "description": "Description of Command N"
            }
          ]
        },
        {
          "scopes": [ "personal", "groupchat" ],
          "commands": [
            {
              "title": "Personal command 1",
              "description": "Description of Personal command 1"
            },
            {
              "title": "Personal command N",
              "description": "Description of Personal command N"
            }
          ]
        }
      ]
    }
  ],
...

Install and test your app

If you've been using App Studio, you can install your app from the Test and distribute tab of the Manifest editor. Alternatively, you can install your app package by clicking the ... overflow menu from the left navigation rail, clicking More apps, then the Upload a custom app link.

Next steps