Send proactive messages Microsoft Teams
Important
Power Virtual Agents capabilities and features are now part of Microsoft Copilot Studio following significant investments in generative AI and enhanced integrations across Microsoft Copilot.
Some articles and screenshots may refer to Power Virtual Agents while we update documentation and training content.
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
Proactive messages can be configured for copilots and classic bots created and customized in Copilot Studio.
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.
Prerequisites
- Your bot must be marked Classic, or it must be a bot you created in the Teams app.
- Learn how to use and create flows.
- Publish your bot.
- Add your bot to Microsoft Teams.
- Getting started with Power Automate.
Known limitations
- You can't send proactive messages in Teams if you've created your bot with the unified authoring canvas.
- 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 Microsoft Copilot Studio 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.
Send a proactive message
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 Microsoft Copilot Studio (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.
When the flow is run, the recipient will receive the proactive message from the bot in Microsoft Teams.
Send a proactive Adaptive Card
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.
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 Microsoft Copilot Studio (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" } ] }
When the flow is run, the recipient will receive the Adaptive Card from the bot in Microsoft Teams.
Wait for user response
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.
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 Microsoft Copilot Studio (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.
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.
Send proactive messages to multiple recipients
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.
Send to teammates
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 Microsoft Copilot Studio (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.
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.
Send to a security group
In this example, the bot will send a reminder to a security group to complete their online training.
Add the Microsoft Entra ID 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 Microsoft Copilot Studio (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.
When the flow runs, each user in the security group will receive the proactive message in a private chat with the bot.
Send proactive message to multiple recipients in parallel
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 Microsoft Copilot Studio 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.
Turn on Concurrency control and set the degree of parallelism.
Configure advanced options for proactive messages
Microsoft Copilot Studio allows you to control detail behavior on your bot under Show advanced options in the Microsoft Teams connector.
Label sent message as a notification
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.
When the recipient is currently in an active chat with the bot
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.
When the recipient hasn't installed the bot
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.
Status code definition
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. |
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for