Share via

Send proactive Microsoft Teams messages

  • Article

After you've published your agent and made the agent available to 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 agent could send a reminder message to complete online training.

Important

Proactive messages can be configured for agents and classic chatbots created and customized in Copilot Studio.

An agent can't deliver messages if the recipient:

  • Doesn't have the agent installed in Microsoft Teams.
  • Has uninstalled the agent.
  • Has blocked the agent.
  • Doesn't have permission to chat with the agent, in which case you need to share the agent with other users.

Prerequisites

Known limitations

  • If the agent is disconnected and reconnected to Microsoft Teams, users won't receive proactive messages until after they reinstall the agent.
  • All proactive messages from Copilot Studio are subject to limits on Power Automate and throttling limits of the Microsoft Teams connector.
  • Proactive messages aren't 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 agent.

Send a proactive message

  1. In Power Automate, open the flow that you want to send a proactive message.

  2. Add the Microsoft Teams connector action Post message in a chat or channel.

  3. For Post as, choose Power Virtual Agents (Preview).

  4. For Post in, choose Chat with bot.

  5. For Bot, select the agent that you want the message to be sent from.

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

  7. For Message, enter the message you want to send.

    Post message action in Power Automate.

When the flow is run, the recipient will receive the proactive message from the agent 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 an agent. To learn how to send Adaptive Cards in an active conversation, see Show an Adaptive Card in Copilot Studio.

In addition to sending proactive messages, you can also send proactive Adaptive Cards.

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.

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

  2. For Post as, choose Power Virtual Agents (Preview).

  3. For Post in, choose Chat with bot.

  4. For Bot, select the agent that you want the message to be sent from.

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

  6. 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"
        }
    ]
}

    Post adaptive card action in Power Automate.

When the flow is run, the recipient will receive the Adaptive Card from the agent 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 an agent. To learn how to send Adaptive Cards in an active conversation, see Show an Adaptive Card in Copilot Studio.

Adaptive Cards support collecting user input. In these scenarios, you'll want to wait for the user's response before the flow continues.

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.

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

  2. For Post as, choose Power Virtual Agents (Preview).

  3. For Post in, choose Chat with bot.

  4. For Message, enter the following template JSON:

    The properties in the actions section determine 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"
        }
    ]
}

  5. For Update message, enter the update message that the recipient will see after providing their response.

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

  7. For Bot, select the agent that you want the card to be sent from.

    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 agent 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

In some scenarios, you might 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 agent installed, then those three recipients won't receive the message.

Send to teammates

In this example, the agent will send a reminder to the members of a team to complete their online training.

  1. Add the Microsoft Teams connector and select the Get a team action in your Power Automate flow.

  2. For Team, choose the team with the members that you want to send the message to.

  3. Add the Office 365 Groups connector and select the List group members action.

  4. For Group Id, select Custom value.

  5. Select Team ID from the dynamic content of the Get a team action.

  6. Add the Microsoft Teams connector and select the Post message in a chat or channel action.

  7. For Post as, choose Power Virtual Agents (Preview).

  8. For Post in, choose Chat with bot.

  9. For Bot, select the agent that you want send the message.

  10. For Recipient, select the dynamic content User Principle Name from the List group members action.

    Send to teammates example.

  11. 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 agent.

Send to a security group

In this example, the agent will send a reminder to a security group to complete their online training.

  1. Add the Microsoft Entra ID connector and select the Get group members action in your Power Automate flow.

  2. For Group Id, enter the security group's GUID.

  3. Add the Microsoft Teams connector and select the Post message in a chat or channel action.

  4. For Post as, choose Power Virtual Agents (Preview).

  5. For Post in, choose Chat with bot.

  6. For Bot, select the agent that you want send the message.

  7. For Recipient, select the dynamic content Group Members User Principle Name from the Get group members action.

  8. For Message, enter the message you want to send.

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

Send proactive message to multiple recipients in parallel

Normally when sending a proactive message to multiple recipients, your agent will send one message after another. However, in some situations, it might be preferable to send the message to multiple recipients at the same time.

Warning

All proactive messages from 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.

  1. In the Apply to each action, select the three horizontal dots (. . .) and then Settings.

    Settings under the more options menu.

  2. Turn on Concurrency control and set the degree of parallelism.

    Slider control for setting the level or concurrency.

Configure advanced options for proactive messages

Copilot Studio allows you to control detailed behavior on your agent under Show advanced options in the Microsoft Teams connector.

Expanded options pane in the connector.

Label sent message as a notification

Label as notification controls whether the message has the text "Notification via" in front of the agent's name. Labeling the agent's response allows the recipient to identify the agent's response to their inquiry.

The setting shows Notification vian agent name.

When the recipient is currently in an active chat with the agent

Sometimes the agent might be sending a proactive message when the recipient is in an active conversation with the agent.

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 agent will send the proactive message as normal.

  • Don't send and succeed: the agent 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 agent 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 agent

The agent can only deliver messages to recipients who have installed the agent in Microsoft Teams. Recipients might not want to install the agent or have uninstalled the agent.

For lower importance messages, you can set the flow run to be marked as succeeded even when the recipient doesn't have the agent 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 agent 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 agent. 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 agent installed.
300 False Message couldn't be delivered because the recipient is in an active conversation with the agent.