Create prompt suggestions

Prompt suggestions are commands that are presented to the users in the Microsoft Teams chat.

Prompt suggestions create an engaging and insightful user experience and help your bot to acquire and retain users by showing them the value of your bot through prompt conversations. You can use prompt suggestions to help your users initiate conversations with your bot and learn how to interact with it.

There are two types of prompt suggestions that you can use:

Prompt starters

Prompt starters help users start a conversation with your bot.

Suggested actions

Suggested actions help users continue conversations with your bot.

Prompt starters

Note

• Your bot can either use a prompt starter or a welcome message. If your bot uses prompt starters, ensure that your bot doesn’t send a welcome message.

• Prompt starters are only supported for one-on-one chat bots.

To enable prompt starters, define the commands property in your bot's app manifest. Each command contains a title and description. The title is the prompt and the description describes what the users accomplish. When the user selects on a prompt starter, the title of the prompt is populated in the compose box. To define commands in your app manifest, you can either use Developer Portal or add them manually in the app manifest.

Developer Portal

To create prompt starters 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. Under Commands, select Add a command.

   

5. Enter the values for the following fields:

   • Command: Appears as the prompt for your bot.
   • Description: A brief explanation of the purpose of the command.

6. Select the personal scope and then select Add. This defines where the command menu must appear.

   

Manually in the app manifest

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

• The command property supports up to 10 commands.
• You can either create prompt starters that work in all scopes or create different prompt starters for each scope.

Manifest example for prompt starters

The manifest example code for prompt starters is as follows:

{
  ⋮
  "bots":[
    {
      "botId":"[Microsoft App ID for your bot]",
      "scopes": [
        "personal"
      ],
      "commandLists":[
        {
          "scopes":[
            "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"
            }
          ]
        }
      ]
    }
  ],
  ...
}

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.

The following illustrates an example of prompt suggestions:

Desktop

Mobile

Prompt starters reappear in the View Prompts flyout above the compose box during a conversation and enables users to review the prompts while interacting with your bot.

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 commands in your bot

Bots in a group or channel respond only when they're @mentioned 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

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's 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's 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's 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)

Suggested actions

Suggested actions help users with ideas of what to ask next, based on the previous response or conversation. Your bot should offer context-specific suggestions to the user, rather than generic or fixed ones. You can use your bot’s large language model (LLM) to generate up to three suggestions along with its responses. Then, you can extract these suggestions and present them as options for the user to choose.

When a user selects a button, it remains visible and accessible on the rich cards. However, for suggested actions, the buttons are designed to disappear after selection to prevent the user from selecting stale options that may no longer be relevant.

Note

• SuggestedActions are only supported for one-on-one chat bots with both text based messages and Adaptive Cards.
• SuggestedActions aren't supported for chat bots with attachments for any conversation type.
• imBack is the only supported action type and Teams display up to three suggested actions.

To add suggested actions to a message, specify a list of card action objects that represent the buttons to be displayed to the user for the sugestedActions property of the activity object.

The following is an example to implement and experience suggested actions:

{
  "type": "message",
  "from": {
    "id": "12345678",
    "name": "sender's name"
  },
  "conversation": {
    "id": "abcd1234",
    "name": "conversation's name"
  },
  "recipient": {
    "id": "1234abcd",
    "name": "recipient's name"
  },
  "text": "What are the tasks for the day.",
  "inputHint": "expectingInput",
  "suggestedActions": {
    "actions": [
      {
        "type": "imBack",
        "title": "Create a new query identifying overdue tasks",
        "value": "Create a new query identifying overdue tasks"
      },
      {
        "type": "imBack",
        "title": "Create a new work item for this feature",
        "value": "Create a new work item for this feature"
            }
        ]
    },
  "replyToId": "5d5cdc723"
}

The following illustrates an example of suggested actions:

Desktop

Mobile

Code sample

Sample name	Description	.NET	Node.js
Prompt starters bot	This sample code describes the implementation of prompt starters for bot through commands property in your bot's app manifest.	View	View

See also

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