Send proactive messages

  • 3 minutes

Proactive messages are sent by a bot to start a conversation. In this unit, you will learn how to send proactive messages.

Requirements for sending proactive messages

To send a proactive message to a user, a group chat, or a team, your bot must have the requisite access to send the message. For a group chat or team, the app that contains your bot must be first installed in that location.

You can proactively install your app in a team using Microsoft Graph, if necessary. You can also use a custom app policy to install an app in your teams and for your organization's users. For certain scenarios, you must proactively install your app using Graph. For a user to receive proactive messages, install the app for the user or make the user a part of a team in which the app is installed.

Send proactive messages

Sending a proactive message is different from sending a regular message. There's no active turnContext to use for a reply. You must create the conversation before sending the message.

To send proactive messages from a bot, you need to:

  1. Obtain Necessary IDs: Retrieve the Microsoft Entra user ID, user ID, team ID, or channel ID. These can be obtained from events when the app is installed, when a new user is added, from the bot context, or by retrieving the list of channels or members in a team where your app is installed.

  2. Create the Conversation: If the conversation doesn't exist or the conversationId is unknown, create the conversation. This requires an aadObjectId or userId, tenantId, and serviceUrl. Store the conversationId or conversationReference object after creation.

  3. Retrieve the Conversation ID: This can be obtained when the app is installed for the first time, from conversation update events, or by proactively installing your app using Graph.

  4. Send the Message: Use the continueConversation method, the conversationId, and tenantId to make a direct API call and send your message.

Remember, the bot must be installed in the team or personal scope before sending a proactive message. The userId is unique to your bot ID and a particular user and cannot be reused between bots. The channelId is global. Proactive messages using aadObjectId are only supported in personal scope.

Example

The following code shows how to send proactive messages:

async SendNotificationToAllUsersAsync(context) {
     const TeamMembers = await TeamsInfo.getPagedMembers(context);
     let Sent_msg_Cout = TeamMembers.members.length;
     TeamMembers.members.map(async member => {
         const ref = TurnContext.getConversationReference(context.activity);
         ref.user = member;
         await context.adapter.createConversation(ref, async (context) => {
             const ref = TurnContext.getConversationReference(context.activity);
             await context.adapter.continueConversation(ref, async (context) => {
                 await context.sendActivity("Proactive hello.");
             });
         });
     });
    await context.sendActivity(MessageFactory.text("Message sent:" + Sent_msg_Cout));
}

Consider when to use proactive messages

Sending proactive messages to users can be an effective way to communicate with your users. However, from their perspective, this message can appear to come to them completely unprompted. Welcome messages will be the first time they've interacted with your app.

It's important to use this functionality sparingly. Provide them with enough information to let them understand why they're being messaged.

Proactive messages generally fall into one of two categories: welcome messages or notifications.

Welcome messages

When proactive messaging is used to send a welcome message to a user, there's no context for why the user receives the message. Also, this is the first interaction of the user with your app. It's an opportunity to create a good first impression. A good user experience ensures better adoption of the app. Poor welcome messages can lead the users to block your app. Write a clear welcome message and iterate on the welcome message if it isn't having the desired effect.

A good welcome message can include the following:

  • Reason for the message - It must be clear to the user why they're receiving the message. If your bot was installed in a channel and you sent a welcome message to all users, then let them know what channel it was installed in and who installed it.

  • Your offer - Users must be able to identify what they can do with your app and what value can you bring to them.

  • Next steps - Users should understand the next steps. For example, invite users to try out a command or interact with your app.

Notification messages

To send notifications using proactive messaging, ensure your users have a clear path to take common actions based on your notification. Ensure users have a clear understanding of why they've received a notification. Good notification messages generally include the following items:

  • What happened? A clear indication of what happened to cause the notification.

  • What was the result? It must be clear, what item is updated to get the notification.

  • Who or what triggered it? Who or what took action, which caused the notification to be sent.

  • What can users do in response? Make it easy for your users to take actions based on your notifications.

  • How can users opt-out? You must provide a path for users to opt-out of more notifications.

  • To send messages to a large group of users, for example to your organization, proactively install your app using Graph.

Scheduled messages

When using proactive messaging to send scheduled messages to users, verify that your time zone is updated to their time zone.