| title | description | keywords | ms.date | ms.topic | author | ms.author | ms.reviewer | ms.custom | ms.service | ms.collection |
|---|---|---|---|---|---|---|---|---|---|---|
Notify bot users in Teams with proactive messages |
Use Power Automate flows to send proactive messages to bot users in Teams, with updates to their conversations, requests for information, and more. |
PVA |
04/21/2023 |
article |
iaanw |
iawilt |
micchow |
teams, flow, ceX |
power-virtual-agents |
virtual-agent |
[!INCLUDE Preview documentation notice]
Select the version of Power Virtual Agents you're using here:
[!div class="op_single_selector"]
After you've published your bot and made the bot available to end users in Microsoft Teams, you can notify users ("recipients") in Microsoft Teams with proactive messages. Proactive messages use Power Automate flows to deliver their content, and are useful in many scenarios, including:
- Letting a recipient know that their earlier request has been completed. For example, the user's time-off request has been approved.
- Providing reminders or news updates. For example, the bot could send a reminder message to complete online training.
Important
A bot can't deliver messages if the recipient:
- Doesn't have the bot installed in Microsoft Teams.
- Has uninstalled the bot.
- Has blocked the bot.
- Doesn't have permission to chat with the bot - in which case you'll need to share the bot with users.
- Learn more about what you can do with Power Virtual Agents.
- Learn how to use and create flows.
- Publish your bot.
- Add your bot to Microsoft Teams.
- Getting started with Power Automate.
- If the bot is disconnected and reconnected to Microsoft Teams, users won't receive proactive messages until after they re-install the bot.
- All proactive messages from Power Virtual Agents are subject to limits on Power Automate and throttling limits of the Microsoft Teams connector.
- Proactive messages won't be logged in conversation transcripts or Analytics sessions.
- Proactive messages must be in the same environment as the Power Automate flow.
- Proactive messages can only be posted to a personal chat with the bot.
-
In Power Automate, open the flow that you want to send a proactive message. Add the Microsoft Teams connector action Post message in a chat or channel.
-
For Post as, choose Power Virtual Agents (Preview).
-
For Post in, choose Chat with bot.
-
For Bot, select the bot that you want the message to be sent from.
-
For Recipient, enter the recipient's name or email address. You can also use dynamic content if the recipient info comes from an earlier step in the flow.
-
For Message, enter the message you want to send.
:::image type="content" source="media/advanced-proactive-message/proactive-message-node.png" alt-text="Post message action in Power Automate.":::
When the flow is run, the recipient will receive the proactive message from the bot in Microsoft Teams.
Important
This section details how to send proactive Adaptive Cards with Power Automate flows. Proactive Adaptive Cards enables users to receive information from an inactive conversation with a bot. To learn how to send Adaptive Cards in an active conversation, see Add Adaptive Cards with Composer.
In addition to sending proactive messages, you can also send proactive Adaptive Cards.
:::image type="content" source="media/advanced-proactive-message/proactive-card.png" alt-text="Screenshot of an adaptive card.":::
Adaptive Cards are an open card exchange format enabling developers to exchange UI content in a common and consistent way. You can author Adaptive Cards by hand in JSON, or if you prefer a drag-and-drop interface, you can use the Adaptive Cards Designer.
Note
Power Automate does not support Adaptive Cards that use the templating feature.
In this example, you'll send an order summary card for the user to review.
-
In Power Automate, add the Microsoft Teams connector action Post adaptive card in a chat or channel at the step where you want to send card in your flow.
-
For Post as, choose Power Virtual Agents (Preview).
-
For Post in, choose Chat with bot.
-
For Bot, select the bot that you want the message to be sent from.
-
For Recipient, enter the recipient's name or email address. You can also use dynamic content if the recipient info comes from an earlier step in the flow.
-
For Adaptive Card, enter the following template JSON:
{ "type": "AdaptiveCard", "$schema": "http://adaptivecards.io/schemas/adaptive-card.json", "version": "1.5", "body": [ { "type": "TextBlock", "text": "Order summary", "wrap": true, "style": "heading" }, { "type": "FactSet", "facts": [ { "title": "Name", "value": "John Doe" }, { "title": "Phone number", "value": "(000) 000-0000" } ] }, { "type": "Container", "items": [ { "type": "FactSet", "facts": [ { "title": "1x", "value": "Steak" }, { "title": "2x", "value": "Side Rice" }, { "title": "1x", "value": "Soft Drink" } ], "spacing": "Small" } ], "spacing": "Small" } ] }:::image type="content" source="media/advanced-proactive-message/adaptive-card-node.png" alt-text="Post adaptive card action in Power Automate.":::
When the flow is run, the recipient will receive the Adaptive Card from the bot in Microsoft Teams.
Important
This section details how to send proactive Adaptive Cards with Power Automate flows. Proactive Adaptive Cards enables users to receive information from an inactive conversation with a bot. To learn how to send Adaptive Cards in an active conversation, see Add Adaptive Cards with Composer.
Adaptive Cards support collecting user input. In these scenarios, you'll want to wait for the user's response before the flow continues.
:::image type="content" source="media/advanced-proactive-message/proactive-card-wait-for-response.png" alt-text="Screenshot of an adaptive card that contains actions for the user.":::
Note
Power Automate does not support Adaptive Cards that use the templating feature.
In this example, you'll send an order confirmation card that allows the user to make changes before the order is submitted.
-
In Power Automate, add the Microsoft Teams connector action Post adaptive card and wait for a response at the step where you want to send card in your flow.
-
For Post as, choose Power Virtual Agents (Preview).
-
For Post in, choose Chat with bot.
-
For Message, enter the following template JSON:
The properties in the
actionssection is what determines the options that are presented to the user.{ "type": "AdaptiveCard", "$schema": "http://adaptivecards.io/schemas/adaptive-card.json", "version": "1.0", "body": [ { "type": "TextBlock", "text": "Order confirmation", "wrap": true, "style": "heading" }, { "type": "FactSet", "facts": [ { "title": "Name", "value": "John Doe" }, { "title": "Phone number", "value": "(000) 000-0000" } ] }, { "type": "Container", "items": [ { "type": "FactSet", "facts": [ { "title": "1x", "value": "Steak" }, { "title": "2x", "value": "Side Rice" }, { "title": "1x", "value": "Soft Drink" } ], "spacing": "Small" } ], "spacing": "Small" } ], "actions": [ { "type": "Action.Submit", "title": "Submit Order" }, { "type": "Action.Submit", "title": "Edit Order" } ] } -
For Update message, enter the update message that the recipient will see after providing their response.
-
For Recipient, enter the recipient's name or email address. You can also use dynamic content if the recipient info comes from an earlier step in the flow.
-
For Bot, select the bot that you want the card to be sent from.
:::image type="content" source="media/advanced-proactive-message/adaptive-card-wait-node.png" alt-text="Post adaptive card and wait for response action in Power Automate.":::
When the flow is run, the recipient will receive the adaptive card from the bot in Microsoft Teams that they can then provide a response to.
To use the response from the recipient, select submitActionId from the dynamic content flyout menu. The value of this variable will be the title of the action the user chose.
Depending on the scenario, you may want to send the same proactive message to multiple recipients.
This section contains examples for sending messages to multiple recipients.
Important
The prerequisites detailed in this topic apply to each recipient.
For example, you can send the same message to 10 recipients in one action. If three of the 10 recipients do not have the bot installed, then those three recipients won't receive the message.
In this example, the bot will send a reminder to the members of a team to complete their online training.
-
Add the Microsoft Teams connector and select the Get a team action in your Power Automate flow.
-
For Team, choose the team with the members that you want to send the message to.
-
Add the Office 365 Groups connector and select the List group members action.
-
For Group Id, select Custom value.
-
Select Team ID from the dynamic content of the Get a team action.
-
Add the Microsoft Teams connector and select the Post message in a chat or channel action.
-
For Post as, choose Power Virtual Agents (Preview).
-
For Post in, choose Chat with bot.
-
For Bot, select the bot that you want send the message.
-
For Recipient, select the dynamic content User Principle Name from the List group members action.
:::image type="content" source="media/advanced-proactive-message/send-to-teammates.png" alt-text="Send to teammates example.":::
-
For Message, enter the message you want to send.
When the flow runs, each user in the team will receive the proactive message in a private chat with the bot.
In this example, the bot will send a reminder to a security group to complete their online training.
-
Add the Azure AD connector and select the Get group members action in your Power Automate flow.
-
For Group Id, enter the security group's GUID.
-
Add the Microsoft Teams connector and select the Post message in a chat or channel action.
-
For Post as, choose Power Virtual Agents (Preview).
-
For Post in, choose Chat with bot.
-
For Bot, select the bot that you want send the message.
-
For Recipient, select the dynamic content Group Members User Principle Name from the Get group members action.
-
For Message, enter the message you want to send.
:::image type="content" source="media/advanced-proactive-message/send-to-security-group.png" alt-text="Send to a security group option.":::
When the flow runs, each user in the security group will receive the proactive message in a private chat with the bot.
Normally when sending a proactive message to multiple recipients, your bot will send one message after another. However in some situations it may be more ideal to send the message to multiple recipients at the same time.
Warning
All proactive messages from Power Virtual Agents are subject to limits on Power Automate and throttling limits of the Microsoft Teams connector.
If you are sending messages to a large group of recipients, you'll see errors if you hit the throttling limit. You can reduce the degree of parallelism, or reduce the number of recipients in the group.
-
In the Apply to each action, select the three horizontal dots (. . .) and then Settings.
:::image type="content" source="media/advanced-proactive-message/node-settings.png" alt-text="Settings under the more options menu.":::
-
Turn on Concurrency control and set the degree of parallelism.
:::image type="content" source="media/advanced-proactive-message/concurrency-control.png" alt-text="Slider control for setting the level or concurrency.":::
Power Virtual Agents allows you to control detail behavior on your bot under Show advanced options in the Microsoft Teams connector.
:::image type="content" source="media/advanced-proactive-message/advanced-options.png" alt-text="Expanded options pane in the connector.":::
Label as notification controls whether the message will have the text "Notification via" in front of the bot's name. Labeling the bot's response allows the recipient to identify the bot's response to their inquiry.
:::image type="content" source="media/advanced-proactive-message/message-label.png" alt-text="The setting shows Notification via bot name.":::
Sometimes the bot might be sending a proactive message when the recipient is in an active conversation with the bot.
You might want to postpone sending the proactive message until they have finished their conversation to not disrupt the conversation flow.
The If chat is active box allows you to control the behavior:
-
Send: the bot will send the proactive message as normal.
-
Don't send and succeed: the bot won't send the proactive message when the recipient is in an active conversation. Status code 300 will be returned.
-
Don't send and fail: the bot won't send the proactive message when the recipient is in an active conversation. The flow run will be marked as a failure.
The bot can only deliver messages to recipients who have installed the bot in Microsoft Teams. Recipients may not want to install the bot or have uninstalled the bot.
For lower importance messages, you can set the flow run to be marked as succeeded even when the recipient doesn't have the bot installed.
The If bot not installed box allows you to control the behavior:
-
Fail: the flow run will be marked as a failure when the recipient hasn't installed the bot in Microsoft Teams.
-
Succeed with status code: the flow run will be marked as succeeded even though the recipient can't receive the message because they haven't installed the bot. Status code 100 will be returned.
You can use the returned status code to define different follow-up behaviors in your flow. For example, you could specify that the flow should try again over a period of time or log a record about the failure.
| Status code | Succeeded (boolean) | Description |
|---|---|---|
| 200 | True | Message is successfully delivered. |
| 100 | False | Message couldn't be delivered because the recipient doesn't have the bot installed. |
| 300 | False | Message couldn't be delivered because the recipient is in an active conversation with the bot. |