Manage conversation and user state

Conversation and User state

You can use Echo Bot With Counter sample as the start point for this how-to. First, create TopicState class to manage the current topic of conversation in TopicState.cs as shown below:

public class TopicState
{
   public string Prompt { get; set; } = "askName";
}

Then create UserProfile class in UserProfile.cs to manage user state.

public class UserProfile
{
    public string UserName { get; set; }
    public string TelephoneNumber { get; set; }
}

The TopicState class has a flag to keep track of where we are in the conversation and uses conversation state to store it. The Prompt is initialized as "askName" to initiate the conversation. Once the bot receives response from the user, Prompt will be redefined as "askNumber" to initiate the next conversation. UserProfile class tracks user name and phone number and stores it in user state.

Property accessors

The EchoBotAccessors class in our example is created as a singleton and passed into the class EchoWithCounterBot : IBot constructor through dependency injection. The EchoBotAccessors class constructor initializes a new instance of the EchoBotAccessors class. It contains the ConversationState, UserState, and associated IStatePropertyAccessor. The conversationState object stores the topic state and userState object that stores the user profile information. The ConversationState and UserState objects are created in the Startup.cs file. The conversation and user state objects are where we persist anything at the conversation and user scope.

Updated the constructor to include UserState as shown below:

public EchoBotAccessors(ConversationState conversationState, UserState userState)
{
    ConversationState = conversationState ?? throw new ArgumentNullException(nameof(conversationState));
    UserState = userState ?? throw new ArgumentNullException(nameof(userState));
}

Create unique names for TopicState and UserProfile accessors.

public static string UserProfileName { get; } = $"{nameof(EchoBotAccessors)}.UserProfile";
public static string TopicStateName { get; } = $"{nameof(EchoBotAccessors)}.TopicState";

Next, define two accessors. The first one stores the topic of the conversation, and the second stores user's name and phone number.

public IStatePropertyAccessor<TopicState> TopicState { get; set; }
public IStatePropertyAccessor<UserProfile> UserProfile { get; set; }

Properties to get the ConversationState is already defined, but you'll need to add UserState as shown below:

public ConversationState ConversationState { get; }
public UserState UserState { get; }

After making the changes, save the file. Next, we will update the Startup class to create UserState object to persist anything at the user-scope. The ConversationState is already exists.

services.AddBot<EchoWithCounterBot>(options =>
{
    ...

    IStorage dataStore = new MemoryStorage();
    
    var conversationState = new ConversationState(dataStore);
    options.State.Add(conversationState);
        
    var userState = new UserState(dataStore);  
    options.State.Add(userState);
});

The line options.State.Add(ConversationState); and options.State.Add(userState); add the conversation state and user state, respectively. Next, create and register state accesssors. Acessors created here are passed into the IBot-derived class on every turn. Modift the code to inclue user state as shown below:

services.AddSingleton<EchoBotAccessors>(sp =>
{
   ...
    var userState = options.State.OfType<UserState>().FirstOrDefault();
    if (userState == null)
    {
        throw new InvalidOperationException("UserState must be defined and added before adding user-scoped state accessors.");
    }
   ...
 });

Next, create the two accessors using TopicState and UserProfile and pass it into the class EchoWithCounterBot : IBot class through dependency injection.

services.AddSingleton<EchoBotAccessors>(sp =>
{
   ...
    var accessors = new BotAccessors(conversationState, userState)
    {
        TopicState = conversationState.CreateProperty<TopicState>("TopicState"),
        UserProfile = userState.CreateProperty<UserProfile>("UserProfile"),
     };

     return accessors;
 });

The conversation and user state are linked to a singleton via the services.AddSingleton code block and saved via a state store accessor in the code starting with var accessors = new BotAccessor(conversationState, userState).

Use conversation and user state properties

In the OnTurnAsync handler of the EchoWithCounterBot : IBot class, modify the code to prompt for user name and then phone number. To track where we are in the conversation, we use the Prompt property defined in the TopicState. This property was initialized a "askName". Once we get the user name, we set it to "askNumber" and set the UserName to the name user typed in. After the phone number is received, you send a confirmation message and set the prompt to 'confirmation' because you are at the end of the conversation.

if (turnContext.Activity.Type == ActivityTypes.Message)
{
    // Get the conversation state from the turn context.
    var convo = await _accessors.TopicState.GetAsync(turnContext, () => new TopicState());
    
    // Get the user state from the turn context.
    var user = await _accessors.UserProfile.GetAsync(turnContext, () => new UserProfile());
    
    // Ask user name. The Prompt was initialiazed as "askName" in the TopicState.cs file.
    if (convo.Prompt == "askName")
    {
        await turnContext.SendActivityAsync("What is your name?");
        
        // Set the Prompt to ask the next question for this conversation
        convo.Prompt = "askNumber";
        
        // Set the property using the accessor
        await _accessors.TopicState.SetAsync(turnContext, convo);
        
        //Save the new prompt into the conversation state.
        await _accessors.ConversationState.SaveChangesAsync(turnContext);
    }
    else if (convo.Prompt == "askNumber")
    {
        // Set the UserName that is defined in the UserProfile class
        user.UserName = turnContext.Activity.Text;
        
        // Use the user name to prompt the user for phone number
        await turnContext.SendActivityAsync($"Hello, {user.UserName}. What's your telephone number?");
        
        // Set the Prompt now that we have collected all the data
        convo.Prompt = "confirmation";
                 
        await _accessors.TopicState.SetAsync(turnContext, convo);
        await _accessors.ConversationState.SaveChangesAsync(turnContext);

        await _accessors.UserProfile.SetAsync(turnContext, user);
        await _accessors.UserState.SaveChangesAsync(turnContext);
    }
    else if (convo.Prompt == "confirmation")
    { 
        // Set the TelephoneNumber that is defined in the UserProfile class
        user.TelephoneNumber = turnContext.Activity.Text;

        await turnContext.SendActivityAsync($"Got it, {user.UserName}. I'll call you later.");

        // initialize prompt
        convo.Prompt = ""; // End of conversation
        await _accessors.TopicState.SetAsync(turnContext, convo);
        await _accessors.ConversationState.SaveChangesAsync(turnContext);
    }
}

Conversation and User state

You can use Echo Bot With Counter sample as the starting point for this how-to. This sample already uses the ConversationState to store the message count. We will need to add a TopicStates object to track our conversation state and UserState to track user information in a userProfile object.

In the main bot's index.js file, add the UserState to the require list:

index.js

// Import required bot services. See https://aka.ms/bot-services to learn more about the different parts of a bot.
const { BotFrameworkAdapter, MemoryStorage, ConversationState, UserState } = require('botbuilder');

Next, create the UserState using MemoryStorage as the storage provider then pass it as the second argument to the MainDialog class.

index.js

// Create conversation state with in-memory storage provider. 
const conversationState = new ConversationState(memoryStorage);
const userState = new UserState(memoryStorage);
// Create the main dialog.
const mainDlg = new MainDialog(conversationState, userState);

In your dialogs/mainDialog/index.js file, update the constructor to accept the userState as the second argument. Then create a topicStates property from the conversationState and create a userProfile property from the userState.

dialogs/mainDialog/index.js

constructor (conversationState, userState) {
    // creates a new state accessor property.see https://aka.ms/about-bot-state-accessors to learn more about the bot state and state accessors 
    this.conversationState = conversationState;
    this.topicState = this.conversationState.createProperty(TOPIC_STATE);

    // User state
    this.userState = userState;
    this.userProfile = this.userState.createProperty(USER_PROFILE);
}

Use conversation and user state properties

In the onTurn handler of the MainDialog class, modify the code to prompt for user name and then phone number. To track where we are in the conversation, we use the prompt property defined in the topicState. This property is initialized to "askName". Once we get the user name, we set it to "askNumber" and set the UserName to the name user typed in. After the phone number is received, you send a confirmation message and set the prompt to undefined because you are at the end of the conversation.

dialogs/mainDialog/index.js

// see https://aka.ms/about-bot-activity-message to learn more about the message and other activity types
if (context.activity.type === 'message') {
    // read from state and set default object if object does not exist in storage.
    let topicState = await this.topicState.get(context, {
        //Define the topic state object
        prompt: "askName"
    });
    let userProfile = await this.userProfile.get(context, {  
        // Define the user's profile object
        "userName": undefined,
        "telephoneNumber": undefined
    });

    if(topicState.prompt == "askName"){
        await context.sendActivity("What is your name?");

        // Set next prompt state
        topicState.prompt = "askNumber";

        // Update state
        await this.topicState.set(context, topicState);
    }
    else if(topicState.prompt == "askNumber"){
        // Set the UserName that is defined in the UserProfile class
        userProfile.userName = context.activity.text;

        // Use the user name to prompt the user for phone number
        await context.sendActivity(`Hello, ${userProfile.userName}. What's your telephone number?`);

        // Set next prompt state
        topicState.prompt = "confirmation";

        // Update states
        await this.topicState.set(context, topicState);
        await this.userProfile.set(context, userProfile);
    }
    else if(topicState.prompt == "confirmation"){
        // Set the phone number
        userProfile.telephoneNumber = context.activity.text;

        // Sent confirmation
        await context.sendActivity(`Got it, ${userProfile.userName}. I'll call you later.`)

        // Set next prompt state
        topicState.prompt = undefined; // End of conversation

        // Update states
        await this.topicState.set(context, topicState);
        await this.userProfile.set(context, userProfile);
    }
    
    // Save state changes to storage
    await this.conversationState.saveChanges(context);
    await this.userState.saveChanges(context);
    
}
else {
    await context.sendActivity(`[${context.activity.type} event detected]`);
}