The chatbot can also proactively reach out to users when it detects a need for their involvement, such as to notify them of new tasks to approve or if their account has become locked out. Suppose you have scenarios where you have to provide commands directly from Job, API, Workflows, or other system components to the Bot and send messages to users. In that case, you will be using the Proactive Messaging capability of the Bot. E.G., a job can trigger a message asking the user to approve a particular business request. In this doc, we will explore properties and create a Sample Proactive Bot Message.
This tutorial describes properties and shows how to add BotProactiveMessageActivity and sample code in a BotFlow. Please refer to the tutorial below for a descriptive and complete walkthrough about how to create and publish a BotFlow.
The BotProactiveMessageActivity allows you to send messages to any active bot conversation. Person.BotConversationReferenceID A conversation reference I.D. is required to initiate a conversation with a user proactively.
Person.BotConversationReferenceID
A conversation reference I.D. is required to initiate a conversation with a user proactively. A reference I.D. implies that the user or Person has an active conversation. A conversation expires if the user closes the communication channel or logs out of the channel (i.e., Teams, Web Chat, etc.). An expired conversation will not have a valid Reference ID, and such a conversation cannot receive messages. Whenever you write any logic for proactive messaging, you should retrieve and check the conversation reference I.D. from the Person.BotConversationReferenceID
You can find the BotProactiveMessageActivity in the Activities toolbox in Workflow Studio. Simply drag and drop the activity into your workflow to use the activity in a workflow.
Properties for BotProactiveMessageActivity
Property | Type | Description |
|---|---|---|
BotTenantId | String | BotTenantId Specifies the Tenant ID. The system administrator can retrieve the Bot Tenant ID of your organization from the Azure portal. |
BotConversationReferenceId | Guid | Specifies the Conversation Reference ID of the user to whom you are sending the message(i.e., Person.BotConversationReferenceID) |
MessageTitle | String | Specifies the subject of the message to show in the notification list. You can see the notification list by sending the Bot the “nfs” command. |
Message | String | Specifies the proactive message you want to send to a user. |
MessageType | TheDotNetFactory.Framework.BotWF.Common.ProactiveMessageType | Specifies how the proactive message should be delivered to the user. The ProactiveMessageType is an enum with the following values:
|
MessageReminder | string | Text to show as a reminder to the user indicating that the user has received a message in the notification list. |
CustomProactiveMessage | TheDotNetFactory.Framework.BotWF.Common.BotCapability | You may use this property to support the advanced handling of proactive messaging. You can find details of CustomProactiveMessage in the section. |
Advanced Proactive Messaging
You can use the CustomProactiveMessage property to support complex proactive messages. The CustomProactiveMessage property is of type BotCapability. Therefore, you may use any bot capability, including hero cards and adaptive cards. Current BotCapability objects include:
BotAttachment
BotAttachmentPrompt
BotAttachmentData
BotChoicePrompt
BotHeroCard (Example below)
BotQuickChoicePrompt
BotTextMessage
BotTextPrompt
Sample Proactive Message
Please follow the steps below to create a sample proactive message. You will be able to create a message and a hero card as shown in the output above for the following steps below.
Add a BotProactiveMessageActivity to your workflow.
Add a BeforeExecute event of the activity and paste the code below.
//Create a Hero Card var heroCard = new BotWF.Common.BotHeroCard { Title = "Some card for fun", Text = "How can I help?", Buttons = new List<BotWF.Common.BotCardAction>(), }; //Add two buttons to the Hero Card. heroCard.Buttons.Add(new BotWF.Common.BotCardAction { Type = BotWF.Common.BotActionTypes.ImBack, Title = "Show Ask to see", Value = "ask" }); heroCard.Buttons.Add(new BotWF.Common.BotCardAction { Type = BotWF.Common.BotActionTypes.ImBack, Title = "Move User", Value = "logout2" }); //Set the Bot Conversation Reference ID. heroCard.BotConversationReferenceId = new Guid("86EB46F9-9A66-4A13-9CAC-A2A00731AF0B"); //Set the Bot Tenant ID. heroCard.BotConversationTenantId = "94d8a558-58b3-43f0-a586-81a833cbaa39"; //Set the message type to immediate reminder and notification list. heroCard.ProactiveMessageType = BotWF.Common.ProactiveMessageType.NotificationReminder; //Set the Reminder message. heroCard.ProactiveMessageReminder = "Hi, I have something for you, please check your nfs list."; //Set the subject of the Message. This will show up in the notification list. heroCard.DisplayName = "Show me the card"; //Set the CustomProactiveMessage property to the hero card. botProactiveMessageActivity1.CustomProactiveMessage = heroCard;
Responding to User Input
The BotConversationFlow class allows you to handle user input following the proactive message. You will have to create an instance of the BotConversationFlow class and specify the name of the Botflow that can respond to the user input.
heroCard.ConversationFlow = new BotConversationFlow().
heroCard.ConversationFlow.WorkflowName = "ResponseToUserBotflow";
//Set any required workflow parameters for the Botflow.
heroCard.ConversationFlow.Parameters = new Dictionary<string, string>() { {"WorkflowProperty1","123"} };