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 UserName, 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.

Web app

Variables can exist at four levels, or scopes:

• Topic variables can only be used in the topics in which they're created. This scope is the default for variables that you create.
• Global variables can be used in all topics. You can change the scope of a topic variable to make it a global variable.
• System variables are created automatically with your agent. They provide more contextual information about the conversation or the user. They're available in all topics.
• Environment variables are created in Power Platform and are read-only in Copilot Studio. They store the parameter keys and values, which then serve as input to various other application objects, including Copilot Studio. Separating the parameters from the consuming objects allows you to change the values within the same environment or when you migrate solutions to other environments. The alternative is leaving hard-coded parameter values within the components that use them.

Variable types

A variable is associated with a base type. The type determines what values the variable can contain and the operators that you can use when you construct a logical expression with it.

Type	Description
String	A sequence of characters used to represent text
Boolean	A logical value that can only be true or false
Number	Any real number
Table	A list of values, but all values must be of the same type
Record	A collection of name-value pairs where values can be of any type
DateTime	A date, time, day of the week, or month relative to a point in time
Choice	A list of string values with associated synonyms
Blank	A placeholder for "no value" or "unknown value"; for more information, see Blanks in Power Fx

A variable's type is set the first time a value is assigned to it. After that, the type for that variable is fixed and it can't be assigned values of any other type. For example, a variable given the starting value of 1 is assigned the type Number. Attempting to assign it to a String value of "apples" results in an error.

When you're testing an agent, a variable might appear temporarily as the type unknown. An unknown variable hasn't been assigned a value yet.

Order of variables is determined from top to bottom of the authoring canvas. Nodes at the top of the authoring canvas are considered before nodes at the bottom.

When you create branches with Condition nodes, branches are ordered from left to right. Nodes in the leftmost branch are considered before nodes in the rightmost branch.

Entities

Copilot Studio uses entities to identify a specific type of information from a user's responses. The identified information is saved in a variable of the type that's appropriate for the information. The following table lists the variable base type associated with prebuilt entities.

Entity	Variable Base Type
Multiple-choice options	Choice
User's entire response	String
Age	Number
Boolean	Boolean
City	String
Color	String
Continent	String
Country or region	String
Date and time	DateTime
Email	String
Event	String
Integer	Integer
Language	String
Money	Number
Number	Number
Ordinal	Number
Organization	String
Percentage	Number
Person name	String
Phone number	String
Point of interest	String
Speed	Number
State	String
Street address	String
Temperature	Number
URL	String
Weight	Number
Zip code	String
Custom entity	Choice

Create a variable

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.

Pick an entity to use

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.

Rename a variable

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.

Set a variable

Typically you use a Question node to save user input to a variable. There might be situations where you want to set the value 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 literal values

Instead of selecting a variable value, you can enter a literal value into any variable.

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, or where you're using more complex types, use a Power Fx formula to set a specific type.

Variables pane

The Variables pane is where you can view all the variables that are available in the 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.

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 it from a global variable back to a topic variable, however. You can also select whether it can receive values from or pass its value to other topics.

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

Environment variables

Environment variables are a Power Platform concept. Environment variables enable the basic application lifecycle management (ALM) scenario of moving an application between Power Platform environments. In this scenario, the application stays exactly the same except for a few key external references that are different between the source environment and the destination environment.

Use Environment variables in the same way as Topic, Global, and System variables. One notable difference is you can only use environment variables in read-only mode. Agent authors cannot modify the environment variable in Copilot Studio. However, administrators can change the value of environment variables in the PowerApps portal.

Environment variable types in Copilot Studio map to PowerApps data types as follows:

Type in Copilot Studio	Type in PowerApps
Decimal number	Number
JSON	Detect the type from the value. If not Json => Unspecified (validation error)
Text	string
Yes/No	Boolean
Data source	string
Secret	String

Note

Environment variable errors are visible in the Test chat and when publishing. However, these errors are not shown in the Topic list because they are not topic variables.

You cannot author or edit environment variables in Copilot Studio. You must use the PowerApps portal to change or set environment variables. From Copilot Studio, you can use the Variables pane to see information about an environment variable. The Variables pane also has a link to the native authoring experience.

Use environment variables for Azure Key Vault secrets

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

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

In addition to the configuration above, you must perform the following actions to authorize Copilot Studio to read this Key Vault:

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.

System variables

Every agent comes with built-in system variables that provide additional information about a conversation.

Note

For more information about voice-enabled agent variables, see Use voice variables.

Not all system variables are shown in the list. You must access these hidden system variables with a Power Fx formula.

To use system variables in a Power Fx formula, you must add System. before the variable name. For example, to include the system variable User.DisplayName in a formula, refer to it as System.User.DisplayName.

Name	Type	Definition
Activity.Attachments	table	The File attachments provided by the user
Activity.Channel	choice	The channel ID of the current conversation
Activity.ChannelData	any	An object that contains channel-specific content
Activity.ChannelId	string	The channel ID of the current conversation, as a string
Activity.From.Id	string	The channel-specific unique ID of the sender
Activity.From.Name	string	The channel-specific user-friendly name of the sender
Activity.Name	string	The name of the event
Activity.Recipient.Id	string	The incoming activity's Type property.
Activity.Recipient.Name	string	Represents the display name for the agent within the channel. In telephony channel context, the value of this variable will be the phone number to which the agent is attached to.
Activity.Text	string	The most recent message sent by the user
Activity.Type	choice	Type of activity
Activity.TypeId	string	Type of activity, as a string
Activity.Value	any	Open-ended value
Bot.EnvironmentId	string	The environment ID of the agent
Bot.Id	string	The ID of the agent
Bot.Name	string	The name of your agent
Bot.SchemaName	string	The schema name of the agent
Bot.TenantId	string	The tenant ID of the agent
ClientPluginActions	choice	Collection of Dynamic Client Plugin Actions to consider for generative orchestration
Conversation.Id	string	The unique ID of the current conversation
Conversation.InTestMode	boolean	Boolean flag that represents if the conversation is happening in test canvas
Conversation.LocalTimeZone	string	Name of the time zone to be used by the user in the IANA Time Zone database format
Conversation.LocalTimeZoneOffset	datetime	The time offset from UTC for the current local time zone
Error.Code	string	The error code for the current error. Note: This variable is supported only if the trigger is On Error.
Error.Message	string	The The error message for the current error. Note: This variable is supported only if the trigger is On Error.
FallbackCount	number	This variable counts the times that a topic couldn't be matched to the user input. Note: This variable is supported only if the trigger is On Unknown Intent.
InactivityTimer.Continue	boolean	Boolean flag that represents whether the timer needs to continued. Note: This variable is supported only if the trigger is Inactivity.
InactivityTimer.Count	number	Number of time OnInactivity timer has fired due to user inactivity after configured time. Note: This variable is supported only if the trigger is Inactivity.
LastMessage.Id	string	The ID of the previous message sent by the user
LastMessage.Text	string	The previous message sent by the user
Recognizer.ExtractedEntities	choice	Represents the extracted entities from triggering message. Note: This variable is supported only if the trigger is On Select Intent.
Recognizer.IntentOptions	choice	Represents the intent options when recognizer return ambiguous results. Note: This variable is supported only if the trigger is On Select Intent.
Recognizer.SelectedIntent	choice	Represents the intent selected from recognizer. Note: This variable is supported only if the trigger is On Select Intent.
Recognizer.TriggeringMessage.Id	string	The ID of the user message that triggered the current topic
Recognizer.TriggeringMessage.Text	string	The user message that triggered the current topic
Recognizer.MultipleTopicsMatchedReason	string	Used to determine why multiple topics were matched. Note: This variable is supported only if the trigger is On Select Intent.
User.Language	choice	This variable is used to set the user language locale per conversation.
SignInReason	choice	Used to determine what sign-in option is needed when triggering the topic. Note: This variable is supported only if the trigger is On Sign In.

Variables for integrated authentication (default)

The following variables are available when you have configured your agent to authenticate with Microsoft. This will use Entra ID authentication and only allow Teams and PowerApps channels. This is the default for new agents.

For more information, see Authentication variables.

Name	Type	Definition
User.DisplayName	string	The display name of the user currently talking to the agent.
User.Email	string	The email address of the user currently talking to the agent.
User.FirstName	string	The first name of the user currently talking to the agent.
User.Id	string	The unique ID of the user currently talking to the agent.
User.IsLoggedIn	boolean	Boolean flag that represents whether the user currently talking to the agent is authenticated or not.
User.LastName	string	The last name of the user currently talking to the agent.
User.PrincipalName	string	The user principal name of the user currently talking to the agent.

Variables for manual authentication with Generic OAuth 2

The following variables are available when you have configured your agent to use the Generic OAuth 2 service provider.

Name	Type	Definition
User.AccessToken	string	The access token for the user authenticating with the agent.
User.DisplayName	string	The display name of the user currently talking to the agent.
User.Id	string	The unique ID of the user currently talking to the agent.
User.IsLoggedIn	boolean	Boolean flag that represents whether the user currently talking to the agent is authenticated or not.

Variables for manual authentication with Microsoft Entra ID

The following variables are available when you have configured your agent to use the Microsoft Entra ID (formerly Azure Active Directory) service providers.

Name	Type	Definition
User.AccessToken	string	The access token for the user authenticating with the agent.
User.DisplayName	string	The display name of the user currently talking to the agent.
User.Email	string	The email address of the user currently talking to the agent.
User.FirstName	string	The first name of the user currently talking to the agent.
User.Id	string	The unique ID of the user currently talking to the agent.
User.IsLoggedIn	boolean	Boolean flag that represents whether the user currently talking to the agent is authenticated or not.
User.LastName	string	The last name of the user currently talking to the agent.
User.PrincipalName	string	The user principal name of the user currently talking to the agent.

Variables for voice-enabled agents

The following variables are only available in voice-enabled agents.

Note

For more information about voice-enabled agent variables, see Use voice variables.

Name	Type	Definition
Activity.InputDTMFKeys	string	The raw DTMF key value that was received from telephony.
Activity.SpeechRecognition.Confidence	number	The confidence score for the ASR hypothesis entire result, 0 to 1.
Activity.SpeechRecognition.MinimallyFormattedText	string	Slightly formatted text of the ASR hypothesis result. For example, Five hundred dollars. Words are spelled out, but basic capitalization and punctuation are included.
Activity.UserInputType	choice	The input type from end user's most recent input. The value can be either test, speech or DTMF.
Conversation.OnlyAllowDTMF	boolean	Boolean flag that represents whether the IVR should be set to DTMF-only mode at runtime.
Conversation.SipUuiHeaderValue	string	The UUI header string used to pass context into IVR on call start.

Pass variables between topics

When you redirect one topic to another, you can pass the values of variables between the original topic and the destination 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.

In this example, we'll 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 that's passed from the Greeting topic.

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

As shown in the Test agent pane, if this topic is triggered first, it asks the user, "What should I call you?" It stores the value in a string variable called userName. The userName 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, {userName}!"

Here's the flow of the Greeting topic:

As shown in the Test agent pane, if this topic is triggered first, it asks the user, "What's your name?" It stores the value in a string variable called UserName. The topic sends the message, "Pleased to meet you, {UserName}!" It then redirects to the Talk to Customer topic, which sends the message, "I hope you're having a wonderful day, {userName}!" Note, however, that the Talk to Customer topic skipped asking for the user's name again. Instead, it used the value of the UserName 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. We'll use our current example, but the same steps will work anytime a topic needs to get a value from an earlier topic.

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 or go to your destination topic.

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

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

4. Select the variable to open the Variable properties pane. Name it userName, and then select Receive values from other topics.

   

5. Add a Message node.

6. In the message box, type I hope you're having a wonderful day,.

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

8. Select the space after the variable and type !.

9. Save the topic.

Set up the source topic

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

1. Go to the source topic.

2. Add a Redirect node and select the destination topic.

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

   

4. Select the > icon, and then select the variable whose value you want to pass.

   

   The Redirect node should look like this:

   

5. Save the topic.

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.

Let's continue with the example from the previous section. We'll 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 being redirected to, the one that provides the value that will be passed back to the original topic. In this example, it's 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 userCity, and then select Return values to original topics.

   

5. 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 doing the redirecting, the one that will receive values from other topics. In our example, it's Greeting.

1. Go to the destination topic.

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

   

3. Save the topic.

Classic

Entity and variable type

Copilot Studio uses entities to identify a specific type of information from a user's responses. A variable type is associated with the identified information when it's saved. The variable type is analogous with the entity.

Each entity or variable type maps to a base type, as listed in the following table. The base type determines the operators that you can use when you construct a logical expression with the corresponding variable. It also determines whether you can feed a variable to a flow or Bot Framework skill as an input parameter.

For example, a Boolean base type maps to an operator "is equal to" with possible values being True or False. A number base type gives you numeric operators such as "is equal to," "is greater than," or "is greater than or equal to," and so on.

Entity	Variable Base Type
Multiple choice options	String
User's entire response	String
Age	Number
Boolean	Boolean
City	String
Color	String
Continent	String
Country or region	String
Date and time	String
Duration	String
Email	String
Event	String
Language	String
Money	String
Number	String
Ordinal	String
Organization	String
Percentage	Number
Person name	String
Phone number	String
Point of interest	String
Speed	Number
State	String
Street address	String
Temperature	Number
URL	String
Weight	Number
Zip code	String
Custom entity	String

Create a variable

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

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

Automatically created variables come with a default name. To rename a variable, select the variable name, enter a new name, and select Done.

Use variables in action nodes

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

Use literal values in action nodes

You can type a literal value into the variable input field in an action node instead of selecting a variable from the menu.

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 Add node (+), then Variable management, and 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 to Copilot Studio. With the Parse Value node, you can send the entire API result as a string:

{
    "Name": "Gary",
    "Position": "PM",
    "Company": "Microsoft",
    "FormerPositions": [{
            "Position": "Engineer"
        }
    ]
}

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. Now you can provide JSON by clicking ‘Get Schema from Sample JSON’. Clicking this opens an editor where you can paste the example.

   

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.

   

You can now use your new variable. Here in the Power Fx editor, you can see that you get full intellisense for the various properties.

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

In the following example, if the event was coming from Teams, you would need to use the Teams developer documentation to find an example of what the incoming event will look like and then use from sample data as outlined in this section.

Passing variables between topics

When you redirect to other topics, you can pass values into variables in the destination topic or get variables back from it. Passing variables between topics is especially useful when you already have information that the topic needs. Your users will appreciate not having to answer the question again. It's also helpful when you refactor and separate your topics into reusable components and you want to pass variables across the topics.

Note

Variables of type Custom Entity, Date and Time, Duration, and Multiple-choice can't be passed between topics.

Receive values from other topics

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

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.

   

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 asks a question, or obtains a variable from an action in some other way, the variable can be returned to the original topic that redirected to it.

In this case, the variable also becomes part of the original topic and can be used like any other variable. This helps you construct the topic so that information the bot obtains is available across topics, reducing the need for global variables.

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.

   

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.

   

Using the Variables pane

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.

   

Using literal values on variable inputs

You can pass literal values as well as variables to a topic. To pass a literal value, type the value you want to use as the input instead of selecting a variable.

Related content

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