Suggested actions article revisions

msteams-platform/bots/how-to/conversations/suggested-actions.md

@@ -9,45 +9,38 @@ ms.date: 6/26/2026
 
 # Dynamically guide users with suggested actions
 
-Suggested actions help users continue conversations with your bot by presenting context-specific next steps in the chat.
+Suggested actions are buttons that agents can dynamically present in chat to help users quickly respond or take action.
 
 :::image type="content" source="~/assets/images/Cards/suggested-actions.png" alt-text="Bot suggested actions." border="false" lightbox="~/assets/images/Cards/suggested-actions.png":::
 
-For guidance on commands that help users start a conversation, see [Create prompt starters](prompt-starters.md).
+Suggested actions are useful for guiding users through multi-step workflows and surfacing agent functionality in chat. Agents can dynamically generate up to three suggested actions for each chat message they send, providing users with actions that fit the context of the conversation.
 
-## Suggested actions
+## User experience
 
-Suggested actions help users with ideas of what to ask next, based on the previous response or conversation. Your agent or bot should offer context-specific suggestions to the user, rather than generic or fixed ones. You can use your agent's or 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. You can build the following suggested actions in your agent or bot:
+Suggested actions are supported in all conversation types. In one-on-one conversations, suggested action buttons are displayed above the compose box and persist until the user selects one or the agent replaces them with a new set of suggested actions.
 
-- `imBack`: Use `imBack` to add suggested actions, set `activity.suggestedActions` to a list of card actions (buttons) to show the user.
-- `Action.Compose`: Use `Action.Compose` to prefill the compose box with a message (including tags, @mentions, and rich content like emojis, GIFs, and other semantic objects).
-- `Action.Submit`: Use `Action.Submit` for suggested action buttons in agent responses for [slash commands](~/agents-in-teams/agent-slash-commands.md) that trigger server-side logic via an invoke activity (no user-visible chat message).
-
-> [!IMPORTANT]
-> The bot can parse up to three actions. Even if you include more than three actions, Teams displays only the first three.
-
-When a user selects a button, it remains visible and accessible on the rich cards. Suggested actions are supported in all scopes:
+:::image type="content" source="~/assets/images/bots/suggested-action-personal-chat.png" alt-text="Image shows suggested actions in a personal chat in a desktop client." border="false" lightbox="~/assets/images/bots/suggested-action-personal-chat.png":::
 
-- `personal`: In one-on-one chats, actions are shown as smart replies, so only the actions from the last message appear.
-- `team` and `groupChat`: In group chats and channels, actions are always saved with the message.
+In group chats and channels, suggested action buttons are displayed with they message they are attached to, and remain available until replaced or removed by the bot. TODO what does this mean?
 
-# [Personal chat](#tab/pc)
+:::image type="content" source="~/assets/images/bots/suggested-action-gc.png" alt-text="Image shows suggested actions in a group chat in a desktop client." border="false" lightbox="~/assets/images/bots/suggested-action-gc.png":::
 
-:::image type="content" source="~/assets/images/bots/suggested-action-personal-chat.png" alt-text="Image shows suggested actions in a personal chat in a desktop client." border="false" lightbox="~/assets/images/bots/suggested-action-personal-chat.png":::
+:::image type="content" source="~/assets/images/bots/suggested-action-channel.png" alt-text="Image shows suggested actions in a channel in a desktop client." border="false" lightbox="~/assets/images/bots/suggested-action-channel.png":::
 
-# [Group chat](#tab/gc)
+## Implement suggested actions
 
-:::image type="content" source="~/assets/images/bots/suggested-action-gc.png" alt-text="Image shows suggested actions in a group chat in a desktop client." border="false" lightbox="~/assets/images/bots/suggested-action-gc.png":::
+EVERYTHING BELOW HERE IS TODO
 
-# [Channel](#tab/channel)
+TODO limitations:
 
-:::image type="content" source="~/assets/images/bots/suggested-action-channel.png" alt-text="Image shows suggested actions in a channel in a desktop client." border="false" lightbox="~/assets/images/bots/suggested-action-channel.png":::
+- Suggested actions aren't supported for chat bots with attachments for any conversation type. (TODO does this mean you can't send them with attachments?)
+- Max 3 per message
 
----
+Suggested actions are based on [card action types](../../../task-modules-and-cards/cards/cards-actions.md).
 
-> [!NOTE]
->
-> `SuggestedActions` aren't supported for chat bots with attachments for any conversation type.
+- `imBack`: Use `imBack` to add suggested actions, set `activity.suggestedActions` to a list of card actions (buttons) to show the user.
+- `Action.Compose`: Use `Action.Compose` to prefill the compose box with a message (including tags, @mentions, and rich content like emojis, GIFs, and other semantic objects).
+- `Action.Submit`: Use `Action.Submit` for suggested action buttons in agent responses for [slash commands](~/agents-in-teams/agent-slash-commands.md) that trigger server-side logic via an invoke activity (no user-visible chat message).
 
 Here are some examples that show how to implement and experience suggested actions using `imBack`, `Action.Compose`, and `Action.Submit`: