Send proactive messages in the v3 C# SDK
APPLIES TO: SDK v3
Typically, each message that a bot sends to the user directly relates to the user's prior input. In some cases, a bot may need to send the user a message that is not directly related to the current topic of conversation or to the last message the user sent. These types of messages are called proactive messages.
Proactive messages can be useful in a variety of scenarios. If a bot sets a timer or reminder, it will need to notify the user when the time arrives. Or, if a bot receives a notification from an external system, it may need to communicate that information to the user immediately. For example, if the user has previously asked the bot to monitor the price of a product, the bot can alert the user if the price of the product has dropped by 20%. Or, if a bot requires some time to compile a response to the user's question, it may inform the user of the delay and allow the conversation to continue in the meantime. When the bot finishes compiling the response to the question, it will share that information with the user.
When implementing proactive messages in your bot:
- Don't send several proactive messages within a short amount of time. Some channels enforce restrictions on how frequently a bot can send messages to the user, and will disable the bot if it violates those restrictions.
- Don't send proactive messages to users who have not previously interacted with the bot or solicited contact with the bot through another means such as e-mail or SMS.
Proactive messages can create unexpected behavior. Consider the following scenario.
In this example, the user has previously asked the bot to monitor prices of a hotel in Las Vegas. The bot launched a background monitoring task, which has been running continuously for the past several days. In the conversation, the user is currently booking a trip to London when the background task triggers a notification message about a discount for the Las Vegas hotel. The bot interjects this information into the conversation, making for a confusing user experience.
How should the bot have handled this situation?
- Wait for the current travel booking to finish, then deliver the notification. This approach would be minimally disruptive, but the delay in communicating the information might cause the user to miss out on the low-price opportunity for the Las Vegas hotel.
- Cancel the current travel booking flow and deliver the notification immediately. This approach delivers the information in a timely fashion but would likely frustrate the user by forcing them start over with their travel booking.
- Interrupt the current booking, clearly change the topic of conversation to the hotel in Las Vegas until the user responds, and then switch back to the in-progress travel booking and continue from where it was interrupted. This approach may seem like the best choice, but it introduces complexity both for the bot developer and the user.
Most commonly, your bot will use some combination of ad hoc proactive messages and other techniques to handle situations like this.
Types of proactive messages
An ad hoc proactive message is the simplest type of proactive message. The bot simply interjects the message into the conversation whenever it is triggered, without any regard for whether the user is currently engaged in a separate topic of conversation with the bot and will not attempt to change the conversation in any way.
To handle notifications more smoothly, consider other ways to integrate the notification into the conversation flow, such as setting a flag in the conversation state or adding the notification to a queue.
Send an ad hoc proactive message
The following code samples show how to send an ad hoc proactive message with the Bot Framework SDK for .NET.
To be able to send an ad hoc message to a user, the bot must first collect and store some information about the user from the current conversation.
public virtual async Task MessageReceivedAsync(IDialogContext context, IAwaitable<IMessageActivity> result)
{
var message = await result;
// Extract data from the user's message that the bot will need later to send an ad hoc message to the user.
// Store the extracted data in a custom class "ConversationStarter" (not shown here).
ConversationStarter.toId = message.From.Id;
ConversationStarter.toName = message.From.Name;
ConversationStarter.fromId = message.Recipient.Id;
ConversationStarter.fromName = message.Recipient.Name;
ConversationStarter.serviceUrl = message.ServiceUrl;
ConversationStarter.channelId = message.ChannelId;
ConversationStarter.conversationId = message.Conversation.Id;
// (Save this information somewhere that it can be accessed later, such as in a database.)
await context.PostAsync("Hello user, good to meet you! I now know your address and can send you notifications in the future.");
context.Wait(MessageReceivedAsync);
}
Note
For simplicity, this example does not specify how to store the user data. It does not matter how the data is stored as long as the bot can retrieve it later.
Now that the data has been stored, the bot can simply retrieve the data, construct the ad hoc proactive message, and send it.
// Use the data stored previously to create the required objects.
var userAccount = new ChannelAccount(toId,toName);
var botAccount = new ChannelAccount(fromId, fromName);
var connector = new ConnectorClient(new Uri(serviceUrl));
// Create a new message.
IMessageActivity message = Activity.CreateMessageActivity();
if (!string.IsNullOrEmpty(conversationId) && !string.IsNullOrEmpty(channelId))
{
// If conversation ID and channel ID was stored previously, use it.
message.ChannelId = channelId;
}
else
{
// Conversation ID was not stored previously, so create a conversation.
// Note: If the user has an existing conversation in a channel, this will likely create a new conversation window.
conversationId = (await connector.Conversations.CreateDirectConversationAsync( botAccount, userAccount)).Id;
}
// Set the address-related properties in the message and send the message.
message.From = botAccount;
message.Recipient = userAccount;
message.Conversation = new ConversationAccount(id: conversationId);
message.Text = "Hello, this is a notification";
message.Locale = "en-us";
await connector.Conversations.SendToConversationAsync((Activity)message);
Note
If the bot specifies a conversation ID that was stored previously, the message will likely be delivered to the user in the existing conversation window on the client. If the bot generates a new conversation ID, the message will be delivered to the user in a new conversation window on the client, provided that the client supports multiple conversation windows.
Send a dialog-based proactive message
The following code samples show how to send a dialog-based proactive message by using the Bot Framework SDK for .NET.
To be able to send a dialog-based proactive message to a user, the bot must first collect and save information from the current conversation.
public virtual async Task MessageReceivedAsync(IDialogContext context, IAwaitable<IMessageActivity> result)
{
var message = await result;
// Store information about this specific point the conversation, so that the bot can resume this conversation later.
var conversationReference = message.ToConversationReference();
ConversationStarter.conversationReference = JsonConvert.SerializeObject(conversationReference);
await context.PostAsync("Greetings, user! I now know how to start a proactive message to you.");
context.Wait(MessageReceivedAsync);
}
When it is time to send the message, the bot creates a new dialog and adds it to the top of the dialog stack. The new dialog takes control of the conversation, delivers the proactive message, closes, and then returns control to the previous dialog in the stack.
// This will interrupt the conversation and send the user to SurveyDialog, then wait until that's done
public static async Task Resume()
{
// Recreate the message from the conversation reference that was saved previously.
var message = JsonConvert.DeserializeObject<ConversationReference>(conversationReference).GetPostToBotMessage();
var client = new ConnectorClient(new Uri(message.ServiceUrl));
// Create a scope that can be used to work with state from bot framework.
using (var scope = DialogModule.BeginLifetimeScope(Conversation.Container, message))
{
var botData = scope.Resolve<IBotData>();
await botData.LoadAsync(CancellationToken.None);
// This is our dialog stack.
var task = scope.Resolve<IDialogTask>();
// Create the new dialog and add it to the stack.
var dialog = new SurveyDialog();
// interrupt the stack. This means that we're stopping whatever conversation that is currently happening with the user
// Then adding this stack to run and once it's finished, we will be back to the original conversation
task.Call(dialog.Void<object, IMessageActivity>(), null);
await task.PollAsync(CancellationToken.None);
// Flush the dialog stack back to its state store.
await botData.FlushAsync(CancellationToken.None);
}
}
The SurveyDialog controls the conversation until it finishes. When its task is finished, it calls context.Done and closes, returning control to the previous dialog.
[Serializable]
public class SurveyDialog : IDialog<object>
{
public async Task StartAsync(IDialogContext context)
{
await context.PostAsync("Hello, I'm the survey dialog. I'm interrupting your conversation to ask you a question. Type \"done\" to resume");
context.Wait(this.MessageReceivedAsync);
}
public virtual async Task MessageReceivedAsync(IDialogContext context, IAwaitable<IMessageActivity> result)
{
if ((await result).Text == "done")
{
await context.PostAsync("Great, back to the original conversation!");
context.Done(String.Empty); // Finish this dialog.
}
else
{
await context.PostAsync("I'm still on the survey until you type \"done\"");
context.Wait(MessageReceivedAsync); // Not done yet.
}
}
}
Sample code
For a complete sample that shows how to send proactive messages using the Bot Framework SDK for .NET, see the Proactive Messages sample in GitHub. Within the Proactive Messages sample, simpleSendMessage shows how to send an ad-hoc proactive message and startNewDialog shows how to send a dialog-based proactive message.