Variables overview
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 |
| 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 |
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 that environment variables are read-only in Copilot Studio. Agent authors can't modify environment variables in Copilot Studio. However, administrators can change the value of environment variables in Power Apps. In Copilot Studio, you can use the Variables panel to see information about an environment variable. The Variables panel also has a link to the native authoring experience.
The published version of an agent that uses environment variables has the values that were set for these variables when the agent was published. Whenever an administrator updates environment variables, you must republish any agents that use these variables, for the changes to be effective at runtime. However, there's one exception: you don't need to republish your agents when the value of an environment variable of type secret changes. Unlike other environment variables, secret variables are retrieved at runtime.
Environment variable types in Copilot Studio map to Power Apps data types as follows:
| Type in Copilot Studio | Type in Power Apps |
|---|---|
| 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.
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 is 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. The error message for the current error. |
| Error.Message | string | 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. |
| 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. |
| User.Language | choice | This variable is used to set the user language locale per conversation. |
Variables for integrated authentication (default)
The following variables are available for agents configured to authenticate with Microsoft. This configuration uses Microsoft Entra ID authentication and 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 family 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 for agents configured 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 for agents configured 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 family name of the user currently talking to the agent. |
| User.PrincipalName | string | The principal name of the user currently talking to the agent. |
Variables for voice-enabled agents
The following variables are only available for 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 Azure Site Recovery hypothesis entire result, 0 to 1. |
| Activity.SpeechRecognition.MinimallyFormattedText | string | Slightly formatted text of the Azure Site Recovery 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 the 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. |