Work with variables

You can use variables to save customers' responses and reuse their content later in the conversation.

You can also use variables to create logical expressions that dynamically route the customer down different conversation paths. For example, save a customer's name in a variable called "customerName," and the agent can address the customer by name as the conversation continues.

Variables can also be passed to, and returned from, other topics and Power Automate flows.

Create a variable

Web app

Any node that prompts you to select a variable as an output, such as a Question node, automatically creates an output variable of the appropriate type.

Tip

Rename nodes to make them easier to identify. Select the node's name field to update the name directly, or select the More icon (…) of the node and select Rename from the menu. You can also rename nodes in the code editor.

It's not possible to rename Trigger nodes and Go to step nodes.

Node names can be up to 500 characters in length.

Classic

In the bot authoring canvas, add a question node. A variable is created automatically in the node.

1. Go to your bot's Topics page and open the topic you want to add a variable to.

2. Select Add node (+), and then select Ask a question.

   

   A variable that contains the user's response is automatically created.

   

Pick an entity to use

Web app

Question nodes are created with multiple-choice options by default. To use a different prebuilt or custom entity, select the Identify box and choose the type of information the agent should listen for.

Classic

By default, a question node is created with multiple-choice options. To use a different prebuilt or custom entity, choose what to identify from the node.

Rename a variable

Web app

Variables are automatically assigned a name when you create them. A best practice is to give your variables meaningful names to make their purpose clear to anyone else who must maintain your agent.

1. Select the variable to open it in the Variable properties pane.

2. Under Variable name, enter a new name for your variable.

Classic

Automatically created variables come with a default name. To rename a variable, select the variable name, enter the desired name in the Variable properties panel, and save your change.

Set a variable

Typically you use a Question node to store user input in a variable. There might be situations where you want to set the value of a variable yourself, however. In those cases, use a Set Variable Value node.

1. Select Add node (+) to add a node, and then select Variable management > Set a variable value.

2. Select the box under Set variable, and then select Create a new variable.

   

   A new variable is created. Its type is unknown until you assign a value to it.

   

3. For To value, assign a value using one of the following options:

   • Type a literal value.
   • Select an existing variable of the same type. This action sets your variable to the same value as the variable you select.
   • Use a Power Fx formula. Power Fx formulas are useful for more complex types where literal values can't be used, such as Table and Record types.

Note

While setting a string type variable, if you encounter a mismatch between Set variable and To value, an error message and Fix type mismatch button appears. Select the button to have Copilot Studio automatically generate a Power Fx formula that resolves the mismatch.

Use variables in action nodes

When you use a variable in an action node, if its base type matches a parameter type specified for a flow, or for a Bot Framework skill, you can feed it to that parameter. The output from action nodes generates new variables.

Use literal values for variable inputs

In nodes where you can set a value for input parameters, you can always enter a literal value instead of selecting another variable as the value.

The node attempts to interpret literal values as a string, a number, or a Boolean. For example, 123 is interpreted as a number. If you want it to be interpreted as a string value instead, you can wrap the value in double quotes, like this: "123".

For some scenarios (for example, scenarios using complex types), you might need to use a Power Fx formula to set a specific type.

Use environment variables for Azure Key Vault secrets

An environment variable can reference a secret in the Key Vault. Secret environment variables are a special case of environment variables with unique considerations.

To create a secret environment variable in the Power Apps portal, you must configure its Key Vault.

To authorize Copilot Studio to read this Key Vault, you must perform the following actions:

1. Assign the Key Vault Secrets User role to the Microsoft Virtual Agents Service application.

2. To authorize all agents from the environment to access the secret, create a tag AllowedEnvironments on the secret and add the allowed environment IDs separated by comma.

3. To authorize only specific agents from the environment to use this Key Vault, create a tag AllowedAgents and put the agent identifier in the format {envId}/{schemaName}. For multiple values, separate the values with commas.

If you reach the maximum number of characters but still need to add more agents, add another tag with a descriptive but unique name (for example: AllowedAgents2).

The secret value is cached in Dialog runtime for five minutes. Unsuccessful reads are cached for 30 seconds.

Warning

By adding the secret in the agent, you might expose the value of this secret to all users who can edit the agent in the environment because such users could edit the agent to return the value in the SendMessage node.

Variables pane

Web app

The Variables pane is where you can view all the variables that are available for a topic, regardless of which nodes they're defined or used in. For each variable, you can select whether it can receive its value from other topics, return its value to other topics, or both. You can also select a variable to edit its properties in the Variable properties pane.

To open the Variables pane, in the topic's menu bar, select Variables.

Classic

Use the Variables pane to select the receive or return status of multiple variables at once.

1. On the topic's menu bar, select Variables.

   

2. For each of the variables in the topic, select whether you want the values to be passed, received, or both between topics.

   

Variable properties pane

In the Variable properties pane, you can rename a variable, see where it's used, or convert it to a global variable. You can't convert a global variable back to a topic variable, however. You can also select whether a topic variable can receive values from or pass its value to other topics.

To open the Variable properties pane for a variable, select the desired variable in the Variables pane. You can also open the Variable properties pane by selecting a variable in any node.

Pass variables between topics

When you redirect one topic to another, you can pass the values of variables from the originating topic to the destination topic and also return values from the destination topic to the originating topic. Passing variables between topics is especially useful when an earlier topic already collected information that a later topic needs. Your users will appreciate not having to answer the same questions again.

Receive values from other topics

When a topic defines a variable (for example, in a Question node), the agent asks the user the question to fill in the variable's value. If the agent has already acquired the value in an earlier topic, there's no reason to ask the question again. In these cases, you can set the variable to Receive values from other topics. When another topic redirects to this one, it can pass either the value of a variable or a literal value to this variable, and skip the question. The experience for the user talking to the agent is seamless.

Web app

In this example, we use two topics, Greeting and Talk to Customer. Both topics ask for the customer's name. However, if the Greeting topic runs first, the Talk to Customer topic skips its question. Instead, it uses the value of the variable passed from the Greeting topic.

Here's the flow of the Talk to Customer topic:

As shown in the test panel, if this topic is triggered first, it asks the user, "What should I call you?" It stores the value in a string variable called customerName. The customerName variable is also set to get its value from other topics. The topic concludes with the message, "I hope you're having a wonderful day, customerName!"

Here's the flow of the Greeting topic:

As shown in the test panel, if this topic is triggered first, it asks the user, "What's your name?" It stores the value in a string variable called customerName. The topic sends the message, "Pleased to meet you, customerName!" It then redirects to the Talk to Customer topic, which sends the message, "I hope you're having a wonderful day, customerName!" Note, however, that the Talk to Customer topic skipped asking for the user's name again. Instead, it used the value of the customerName variable passed from the Greeting topic.

Finally, here's that second conversation again, this time from the perspective of the Talk to Customer topic:

Let's walk through the steps to set up a topic to receive values from other topics. Our example scenario uses the predefined topic Greeting as the source topic, and a new topic Talk to Customer as the destination topic, but the same steps work for any topic that should use a value from an earlier topic when possible.

Set up the destination topic

The destination topic is the topic being redirected to, the one that will receive values from other topics. In our example, it's Talk to Customer.

1. Create a new topic and call it "Talk to Customer."

2. Add trigger phrases such as "talk to me," "speak with me," "chat with me."

3. Add a Question node and enter "What should I call you?" for the message.

4. Under Identify, select the prebuilt entity Person name.

5. Select the name of the variable. The Variable properties panel opens.

6. Replace the default name with "customerName", and then select Receive values from other topics.

   

7. Add a Message node.

8. In the message box, enter "I hope you're having a wonderful day, ".

9. Select the Insert variable icon ({x}), and then select customerName.

10. Select the space after the variable and enter "!".

11. Save the topic.

Set up the source topic

The source topic is the topic doing the redirecting, the one that provides the value and passes it to the destination topic. In our example, it's Greeting.

1. Go to the Greeting topic and delete the default nodes, except for the Trigger node.

2. Add a Question node and enter "What's your name?" for the message.

3. Under Identify, select the prebuilt entity Person name.

4. Replace the default name with "customerNameFromGreeting".

5. Add a Message node.

6. In the message box, enter "Pleased to meet you, ".

7. Select the Insert variable icon ({x}), and then select customerNameFromGreeting.

8. Select the space after the variable and enter "!".

9. Add a Redirect node, and select the destination topic Talk to Customer.

10. Select Add input, and then select the variable from the destination topic that you want to pass a value to.

    

11. Select the > icon, and then select the variable whose value you want to pass, customerNameFromGreeting, in this example.

    The Redirect node should look like this:

    

12. Save the topic.

Classic

To receive values from other topics, set the variable's property:

1. In the Question node, select the variable that you want to receive values from other topics.

2. In the Variables properties pane, under Topic (limited scope) select Receive values from other topics.

   

   Note

   Variables of type Date and time, Duration, or Multiple choice, and variables based on a custom entity can't be passed between topics.

3. Save the topic.

4. Go to a topic that you want to redirect to. Follow the steps in Redirect to another topic to redirect to the correct topic.

5. Select + Add input for destination topic.

   

6. Select a variable in the redirected topic that you want to pass the variable to.

   

7. Under Enter or select a value, select the variable in the current topic that you want to pass to the redirected topic.

   

   The variable is shown in the redirected node.

   

Return values to original topics

When a topic is redirected to and obtains a variable by asking a question or in some other way, the variable can be returned to the original topic. The variable becomes part of the original topic and can be used like any other variable. Information the agent obtains is thus available across topics, reducing the need for global variables.

Web app

Let's continue with the example from the previous section. We ask a new question in the Talk to Customer topic, and then return the answer to the Greeting topic.

Set up the source topic for a returned variable

When you're returning a variable to a topic, the source topic is the topic that provides the value to pass back to the original topic. In this example, the source topic is Talk to Customer.

1. Go to the source topic.

2. Add a Question node and enter "What city do you live in?" for the message.

3. Under Identify, select the prebuilt entity City.

4. Select the variable to open the Variable properties pane. Name it "customerCity," and then select Return values to original topics.

   

5. Add a Message node.

6. Select the Insert variable icon ({x}), and then select customerCity.

7. After the variable in the message box, enter " must be beautiful this time of year!".

8. Save the topic.

Set up the destination topic for a returned variable

When you're returning a variable to a topic, the destination topic is the topic that receives values from the current topic. In our example, the destination topic is Greeting.

1. Go to the destination topic.

2. The variable you selected in the source topic should appear on the Redirect node as an output variable.

   

3. Save the topic.

Classic

To return a variable to the original topic, set the variable's property:

1. In the Question node, select the variable that you want to receive values from other topics.

2. In the Variables properties pane, under Topic (limited scope) select Return values to original topics.

   

   Note

   Variables of type Date and time, Duration, or Multiple choice, and variables based on a custom entity can't be passed between topics.

3. Save the topic.

4. Go to a topic that you want to redirect to. Follow the steps in Redirect to another topic to redirect to the correct topic.

   The variable that's being returned to the topic is shown in the redirected topic. Use the returned variable in your topic.

   

Parse value node

The Parse value node allows you to convert a value of one type, to a value of another type. When adding a node to a topic, select the Add node icon , point to Variable management, and select Parse value.

Key scenarios using the Parse value node focus on converting raw JSON or untyped variables (whose value or structure isn't know until runtime; for example ChannelData) to concrete types.

The process starts when a flow is called, which in turn calls an API. The API then returns a result. Typically, you would need to parse this response and return one or more primitive variables. With the Parse value node, you can send the entire API result as a string. For example:

{
    "Name": "Parker",
    "Position": "Product manager",
    "Company": "Contoso",
    "FormerPositions": [{
            "Position": "Customer service representative"
        }
    ]
}

The string variable that you have now can be converted to a Record variable, with full intellisense support in Power Fx, using this new node. An example using sample data will help illustrate this process.

Example of using the Parse value node

1. Add a Parse value node, and select the variable you want to parse.

   

2. Select the data type. In this case choose From Sample Data.

   

3. Select Get Schema from Sample JSON and enter the desired JSON example in the editor that opens.

   

4. Finally, specify which variable you want to place the parsed value into. Usually you would create a new variable for this.

   

   Note that the output variable is now of the correct type: Record.

   

As well as parsing JSON strings, a key use of the Parse value node is parsing UntypedObjects at runtime. The most common use case is when you receive an event and you need to parse the event value. Or you might want to parse the System.Activity.ChannelData property, which varies at runtime by channel.

If you were to parse information from an event coming from Teams, you would need to use the Teams developer documentation to find an example of what the expected event might look like and then use this example as sample data as outlined previously in this section.

Related content

• Use variables to carry content across topics
• Customize the look and feel of an agent