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

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.

{
  ⋮
  "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"
            }
          ]
        }
      ]
    }
  ],
  ...
}

The following illustrates an example of prompt suggestions:

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.

// 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();

// 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);

# 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.

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:

Code sample

See also

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