Create a commands menu

Note

It's recommended that you'd create a command bot by following the step-by-step guide to Build command bot with JavaScript using the new generation development tool for Teams. For more information about Teams Toolkit, see Teams Toolkit Overview for Visual Studio Code and Teams Toolkit overview for Visual Studio.

Important

The code samples in this section are based on version 4.6 and later versions of the Bot Framework SDK. If you are looking for documentation for earlier versions, see the bots - v3 SDK section in the Legacy SDKs folder of the documentation.

To define a set of core commands that your bot can respond to, you can add a command menu with a dropdown list of commands for your bot. The list of commands is presented to the users in the compose message area when they are in conversation with your bot. Select a command from the list to insert the command string into the compose message box and select Send.

Desktop

Mobile

Create a command menu for your bot

Command menus are defined in your app manifest. You can either use Developer Portal to create them or add them manually in the app manifest.

Create a command menu for your bot using Developer Portal

A prerequisite to create a command menu for your bot is that you must edit an existing app manifest. The steps to add a command menu are the same, whether you create a new manifest or edit an existing one.

To create a command menu for your bot using Developer Portal:

1. Open Teams and select Apps from the left pane. In the Apps page, search for Developer Portal, and then select Open.

   

2. In Developer Portal, select the Apps tab. If you don't have an existing app package, you can create or import an existing app. For more information, see Developer Portal for Teams.

3. Select Apps tab, select App features from the left pane, and then select Bots.

4. Select Add a command under Commands section.

   

5. Enter the Command that appears as the command menu for your bot.

6. Enter the Description that appears under the command text in the menu. Description must be a brief explanation of the purpose of the command.

7. Select the Scope check box and then select Add. This defines where the command menu must appear.

   

Create a command menu for your bot by editing Manifest.json

Another way to create a command menu is to create it directly in the manifest file while developing your bot source code. To use this method, follow these points:

• Each menu supports up to ten commands.
• Create a single command menu that works in all scopes.
• Create a different command menu for each scope.

Manifest example for single menu for both scopes

The manifest example code for single menu for both scopes is as follows:

{
  ⋮
  "bots":[
    {
      "botId":"[Microsoft App ID for your bot]",
      "scopes": [
        "personal",
        "team"
      ],
      "commandLists":[
        {
          "scopes":[
            "team",
            "personal"
          ],
          "commands":[
            {
              "title":"Help",
              "description":"Displays this help message"
            },
            {
              "title":"Search Flights",
              "description":"Search flights from Seattle to Phoenix May 2-5 departing after 3pm"
            },
            {
              "title":"Search Hotels",
              "description":"Search hotels in Portland tonight"
            },
            {
              "title":"Best Time to Fly",
              "description":"Best time to fly to London for a 5 day trip this summer"
            }
          ]
        }
      ]
    }
  ],
  ...
}

Manifest example for the menu for each scope

The manifest example code for the menu for each scope is as follows:

{
  ...
  "bots":[
    {
      "botId":"<Microsoft app ID for your bot>",
      "scopes": [
        "groupChat",
        "team"
      ],
      "commandLists":[
        {
          "scopes":[
            "team"
          ],
          "commands":[
            {
            "title":"help",
            "description":"Displays this help message for channels"
            }
          ]
        },
        {
          "scopes":[
            "groupChat"
          ],
          "commands":[
            {
            "title":"help",
            "description":"Displays this help message for group chat"
            }
          ]
        }
      ]
    }
  ],
  ...
}

You must handle menu commands in your bot code as you handle any message from users. You can handle menu commands in your bot code by parsing out the @Mention portion of the message text.

Handle menu commands in your bot code

Bots in a group or channel respond only when they are mentioned @botname in a message. Every message received by a bot when in a group or channel scope contains its name in the message text. Before handling the command being returned, your message parsing must handle the message received by a bot with its name.

Note

To handle the commands in code, they are sent to your bot as a regular message. You must handle them as you would handle any other message from your users. The commands in code insert pre-configured text into the text box. The user must then send that text as they do for any other message.

C#

• SDK reference

• Sample code reference

You can parse out the @Mention portion of the message text using a static method provided with the Microsoft Bot Framework. It is a method of the Activity class named RemoveRecipientMention.

The C# code to parse out the @Mention portion of the message text is as follows:

// Remove recipient mention text from Text property.
// Use with caution because this function is altering the text on the Activity.
var modifiedText = turnContext.Activity.RemoveRecipientMention();

JavaScript

• SDK reference

• Sample code reference

You can parse out the @Mention portion of the message text using a static method provided with the Bot Framework. It is a method of the TurnContext class named removeMentionText.

The JavaScript code to parse out the @Mention portion of the message text is as follows:

// Remove mention text from Text property, this function is altering the text on the Activity.
const modifiedText = TurnContext.removeMentionText(turnContext.activity, turnContext.activity.recipient.id);

Python

• SDK reference

• Sample code reference

You can parse out the @Mention portion of the message text using a static method provided with the Bot Framework. It is a method of the TurnContext class named remove_recipient_mention.

The Python code to parse out the @Mention portion of the message text is as follows:

# Remove recipient mention text from Text property, this function is altering the text on the Activity.
modified_text = TurnContext.remove_recipient_mention(turn_context.activity)

To enable smooth functioning of your bot code, there are few best practices that you must follow.

Command menu best practices

Following are the command menu best practices:

• Keep it simple: The bot menu is meant to present the key capabilities of your bot.
• Keep it short: Menu options must not be long and must not be complex natural language statements. They must be simple commands.
• Keep it invokable: Bot menu actions or commands must always be available, regardless of the state of the conversation or the dialog the bot is in.

Note

If you remove any commands from your manifest, you must redeploy your app to implement the changes. In general, any changes to the manifest require you to redeploy your app.

Next step

Channel and group chat conversations with a bot

See also

• Build bots for Teams
• App manifest schema for Teams
• Messages in bot conversations
• Adaptive Cards for bot developers