[Doc Improvement][Update suggested-actions][5569622] - #14466
[Doc Improvement][Update suggested-actions][5569622]#14466v-shalinirob wants to merge 90 commits into
Conversation
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
|
Learn Build status updates of commit d456baa: ✅ Validation status: passed
For more details, please refer to the build report. |
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit 56166af: ✅ Validation status: passed
For more details, please refer to the build report. |
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit 53f9f72: ✅ Validation status: passed
For more details, please refer to the build report. |
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit 5766adc: ✅ Validation status: passed
For more details, please refer to the build report. |
| To help users start a conversation, see [Create prompt starters](prompt-starters.md). | ||
|
|
||
| For guidance on commands that help users start a conversation, see [Create prompt starters](prompt-starters.md). | ||
| ## Understand suggested actions |
There was a problem hiding this comment.
This content should be part of the Implementation section. That section should lead with a brief one-sentence explanation of what each action type does, and then have dedicated H3s for each action type. The introduction to the article can mention the most common ones to help with understanding scenarios.
These action types should also be titled with prose names, not their technical implementation - when describing the feature, developers don't know what imback means yet, the action is "Predetermined chat response" or something similar.
| - `Action.Submit`: Use `Action.Submit` when the selected option should trigger server-side logic without posting a user-visible chat message. For example, an approval agent can offer Approve and Reject buttons for a slash-command response and process the decision silently on the server. | ||
|
|
||
| When a user selects a button, it remains visible and accessible on the rich cards. Suggested actions are supported in all scopes: | ||
| ## User experience |
There was a problem hiding this comment.
This needs some additional text explaining how suggested actions are supported in all conversation types, and where they are placed in each.
| > `SuggestedActions` aren't supported for chat bots with attachments for any conversation type. | ||
| ## Implement suggested actions | ||
|
|
||
| Your agent or app should offer context-specific suggestions to the user, rather than generic or fixed ones. Implement each suggested action by first confirming the intended user outcome, then validating its behavior in the supported conversation scopes, and finally adding the corresponding payload and handler. |
There was a problem hiding this comment.
A lot of this should be in the best practices section, this section should focus only on technical implementation.
| # 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 present context-specific next steps after an agent or app response, so users can refine a request, continue a workflow, or make a choice with one selection. Use suggested actions when the next step depends on the current conversation. |
There was a problem hiding this comment.
| Suggested actions present context-specific next steps after an agent or app response, so users can refine a request, continue a workflow, or make a choice with one selection. Use suggested actions when the next step depends on the current conversation. | |
| 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="Suggested action buttons displayed below an agent response in a Teams chat." border="false" lightbox="~/assets/images/Cards/suggested-actions.png"::: | ||
|
|
||
| :::image type="content" source="~/assets/images/Cards/suggested-actions.png" alt-text="Bot suggested actions." border="false" lightbox="~/assets/images/Cards/suggested-actions.png"::: | ||
| To help users start a conversation, see [Create prompt starters](prompt-starters.md). |
There was a problem hiding this comment.
| To help users start a conversation, see [Create prompt starters](prompt-starters.md). | |
| Suggested actions are useful for requesting user approval or input, guiding users through multi-step workflows, and surfacing agent functionality in the flow of a conversation. The buttons can be configured to send a predetermined chat response on the user's behalf or trigger server-side logic without posting a chat message. | |
| Agents can dynamically provide up to three suggested action buttons with each chat message they send. |
| Here are some examples that show how to implement and experience suggested actions using `imBack`, `Action.Compose`, and `Action.Submit`: | ||
|
|
||
| # [`imBack`](#tab/iamback) | ||
| ### Add `imBack` action |
There was a problem hiding this comment.
Same as above, the action types should be represented in natural language, not by their implementation names.
|
|
||
| To add the `imBack` suggested action to a message, specify a list of [card action](/azure/bot-service/rest-api/bot-framework-rest-connector-api-reference) objects that represent the buttons to be displayed to the user for the [`suggestedActions`](/dotnet/api/microsoft.bot.builder.messagefactory.suggestedactions) property of the [activity](/azure/bot-service/rest-api/bot-framework-rest-connector-api-reference) object. | ||
|
|
||
| #### Teams SDK implementation |
There was a problem hiding this comment.
These samples are good for illustrating AI-generated suggested actions (which is a key aspect of this feature) but each action type should lead with a minimal implementation that shows basic usage of the most relevant parts of the API, just a couple of lines of code.
| # [`Action.Compose`](#tab/actioncompose) | ||
| This example shows how to attach `suggestedActions` to the agent message and set `inputHint` to `expectingInput` to prompt a user response. The `actions` array defines the available choices, each using `imBack` with a button `title` and a returned `value`. When selected, the value is sent back to the agent or app as the user response, enabling it to route the conversation to the appropriate intent or operation. | ||
|
|
||
| ### Add `Action.Compose` action |
There was a problem hiding this comment.
It's fine if there's no first-class Teams SDK implementation, but instead of showing just the raw JSON payload, we should show how to supply that payload to a send() call.
| Suggested actions behavior varies by conversation scope. Selected actions on rich cards remain visible in group chats and channels, while personal chats show smart replies only from the latest message. | ||
|
|
||
| Teams displays and processes up to three suggested actions. They are not supported in messages with attachments. Test each supported scope for visibility and persistence. | ||
|
|
||
| Before returning `Action.Compose`, verify that the conversation channel and host support it; unsupported hosts display an error. |
There was a problem hiding this comment.
These three are core aspects/limitation of the feature, not practices/design guidance
| ::: zone-end | ||
|
|
||
| --- | ||
| ### Guidance for approval workflow using `Action.Submit` |
There was a problem hiding this comment.
Looking at what's going into the targeted messages article, I'm not really sure this level of coverage is needed here. This could probably be condensed into a couple of sentences that would go into the best practices section about how user approval (for private -> public repost of targeted messages, or really anything) is a good scenario for suggested actions.
Update Suggested actions as per the inputs in PR #14380 and PR #14381, and PR 14482 comment.
Preview URL: Dynamically guide users with suggested actions