Work with global variables

1. Create a variable or use the Variables panel to open an existing variable.

2. On the Variable properties panel, select Global (any topic can access).

   The variable name is given the prefix Global. to differentiate it from topic-level variables. For example, the variable UserName is displayed as Global.UserName.

3. Save the topic.

1. Select the desired variable.

2. In the Variable properties panel, under Usage, select Bot (any topic can access).

3. The variable name is marked with a prefix bot., to differentiate it from the topic-level variables. For example, the variable UserEmail now appears as bot.UserEmail.

When you're composing a message in a Message node or a Question node, select the {x} icon to view the variables that are available to the topic. Global variables appear in the Custom tab along with any topic variables. Variables are listed in alphabetical order.

When you're composing a message in a Message node or a Question node, select the {x} icon to view the variables that are available to the topic. Variables are listed in alphabetical order, and all global variables appear together because they all begin with bot..

When you use a condition node, a flow action node, or a skill node, you also see global variables available there.

1. Select the desired global variable on the authoring canvas, or in the Variables panel.

2. On the Variable properties panel, in the Reference section, select View all references.

3. Switch to the Other tab, and select any topic where the variable is used to go directly to that topic and node.

Select the desired variable on the authoring canvas. The Variable properties panel appears.

• To go directly to the node where the global variable was created, select Go to source.

• To go to a topic that uses this variable, select the desired topic in the Used by section.

By default, the value of a global variable persists until the session ends. The Clear variable values node resets the values of global variables and is used in the Reset Conversation system topic. When a redirection triggers that topic (or when the user enters a phrase such as "Start over"), all global variables are reset.

Global variables are accessible from any topic, and their value persists throughout a session.

The value is only cleared when the agent user is redirected to the Start Over topic, or when the user triggers this topic directly (for example, by typing "Start over"). In this case, all global variables are reset and don't have a value.

Global variable initialization

If a global variable is triggered before it's initialized (or "filled in"), the agent automatically triggers the part of the topic where the global variable is first defined—even when it's in a different topic—before returning to the original topic. This behavior allows the agent to have all the variables filled in without interrupting the conversation.

For example, the customer starts the conversation on the "Appointment booking" topic, in which a global variable bot.UserName is used. However, the bot.UserName variable is first defined in the "Welcome" topic.

When the conversation comes to the point in the "Appointment booking" topic where bot.UserName is referenced, the agent seamlessly pivots to the question node where bot.UserName is first defined.

After the customer answers the question, the agent resumes the "Appointment booking" topic.

Global variable behavior when implementing actions via Power Automate flows or skills

Sometimes, you might use a flow or skill to initialize or fill in a variable.

When a user interacts with the agent, however, the variable might be filled in at an earlier point in the conversation, or you might have already set the variables externally.

In this situation, the flow or skill still runs and fills in the variable, overwriting whatever was previously stored in the variable.

To make sure the agent starts a conversation with some context, you can use a global variable and set its value from an external source. Let's say that your site requires users to sign in. If you store a user's name in a global variable and pass it to your agent, the agent can greet customers by name before they start typing their first question. Another example scenario is passing context from Dynamics 365 Customer Service to an agent so it can start the conversation with knowledge of what the customer wants to achieve.

To prevent undesirable latency, you can specify how long your agent can wait for a value. You can also set a default value to use when the external source fails to respond in a timely fashion.

1. Create a dedicated topic to hold the configuration for all the variables meant to be set from external sources. You might name this topic "Set context variables" for example. This topic doesn't serve any other purposes, so it doesn't need to have trigger phrases set.

2. Add a Set variable value node to your dedicated topic.

3. Under Set variable, open the variable picker, and select Create a new variable.

4. Select the default name of the new variable. The Variable properties panel appears.

5. Replace the default name to one that matches exactly the name of the variable being passed in from the external system.

6. Under Usage, select Global (any topic can access), and External sources can set values.

7. Under Reference, select the three dots (⋮) in the upper-right corner, and select Get value from this node if empty.

8. (Optional) Set a time-out delay, in milliseconds. This value determines how long your agent can wait for the variable to be set by an external source before timing out and continuing with the default value you set in the Set variable value node. This setting is relevant in scenarios where the variable depends on a long-running or asynchronous process, but your agent must respect a maximum latency to ensure a good user experience.

   For variables coming from Omnichannel for Customer Service, we suggest a value of 10 seconds (10,000 ms) as a maximum wait time.

9. In the Set variable value node, enter the default value to use if the time-out is reached. At runtime, your agent will expect values with the same data type. If you want this default value to be an empty string, use Text("") as a formula.

   

10. For any other values you expect to come from an external system, add more Set variable value nodes to your dedicated topic, and configure the required global variables in the same fashion.

Thus configured, your agent is ready to test. When the agent is invoked, instead of waiting indefinitely for all variables to be populated, your agent can immediately start sending any messages that aren't dependent on the variables being passed in. When your agent attempts to access a variable that's being set externally, it pauses until the value arrives or the time-out occurs. Learn more about optimizing agents to minimize latency.

You can set a global variable to be initialized from an external source. This action lets the agent start the conversation with some context.

For example, a customer brings up an agent chat from your website, and the site already knows the customer's name. You let the agent know the user's name before starting the conversation, and the agent can have a more intelligent conversation with the customer without having to ask for their name again.

1. Select the desired global variable.

2. On the Variable properties panel, select External sources can set values.

If you're embedding your agent in a simple web page, you can append variables and their definitions to the agent's URL. Or, if you'd like a little more control, you can use a <script> code block to call and use variables programmatically.

The variable name in the query string of the URL must match the name of the global variable without the Global. prefix. For example, a global variable Global.UserName would be referred to as UserName in the query.

The examples that follow uses a basic declaration for the variables. In a production scenario, you might pass in as the query parameter or variable definition another variable that already stores the user's name (for example, if you have the user name from a sign-in script).

Append the variables and their definitions to the agent's URL as query string parameters in the format botURL?variableName1=variableDefinition1&variableName2=variableDefinition2.

For example:

• You have a global variable named Global.UserName.
• Your agent's URL is https://web.powerva.microsoft.com/webchat/bots/12345.
• To pass in the user's name when starting an agent conversation on your website, attach the UserName= query string as: https://web.powerva.microsoft.com/webchat/bots/12345?UserName=Ana.

The parameter name is case-insensitive. username=Ana would also work in this example.

You can append the variables and their definitions if you're simply embedding your agent in a simple webpage, or you can use a <script> code block to call and use variables programmatically.

In the examples described here, a simple declaration is made for the variables. In a production scenario, you might pass in as the query parameter or variable definition another variable that already stores the user's name (for example, if you have the user name from a sign-in script).

1. Append the variables and their definitions to the agent's URL as query string parameters (in the format of botURL?variableName1=variableDefinition1&variableName2=variableDefinition2), for example:

   • You have a global variable named bot.UserEmail.
   • Your agent's URL is https://web.powerva.microsoft.com/webchat/bots/12345.
   • To pass in the user name when starting an agent conversation on a website, you can attach the UserEmail= query string as: https://web.powerva.microsoft.com/webchat/bots/12345?UserEmail=Ana@contoso.com.

2. The parameter name is case-insensitive. This means useremail=Ana@contoso.com would also work in this example.

1. In the <script> section on the page where you have your agent, define the variables as follows, substituting variableName1 for the variable name without the Global. prefix and variableDefinition1 for the definition. Separate multiple variables with commas (,).

      const store = WebChat.createStore({}, ({ dispatch }) => next => action => {
        if (action.type === 'DIRECT_LINE/CONNECT_FULFILLED') {
          dispatch({
             type: "WEB_CHAT/SEND_EVENT",
             payload: {
               name: "pvaSetContext",
               value: {
                  "variableName1": "variableDefinition1",
                  "variableName2": "variableDefinition2"
               }
             },
           });
         }
           return next(action);
       });
   

2. In your <script> section, call the store when you embed your agent, as in the following example where store is called just before where styleOptions is called (you must replace the BOT_ID with your agent's ID):

   const BOT_ID = "12345-5678";
   const theURL = "https://powerva.microsoft.com/api/botmanagement/v1/directline/directlinetoken?botId=" + BOT_ID;
   
   fetch(theURL)
       .then(response => response.json())
       .then(conversationInfo => {
           window.WebChat.renderWebChat(
               {
                   directLine: window.WebChat.createDirectLine({
                       token: conversationInfo.token,
                   }),
                   store,
                   styleOptions
               },
               document.getElementById('webchat')
           );
       })
       .catch(err => console.error("An error occurred: " + err));
   

1. In the <script> section on the page where you have your agent, define the variables as follows, substituting variableName1 for the variable name without the bot. prefix and variableDefinition1 for the definition. Separate multiple variables with commas ,.

      const store = WebChat.createStore({}, ({ dispatch }) => next => action => {
        if (action.type === 'DIRECT_LINE/CONNECT_FULFILLED') {
          dispatch({
             type: "WEB_CHAT/SEND_EVENT",
             payload: {
               name: "pvaSetContext",
               value: {
                  "variableName1": "variableDefinition1",
                  "variableName2": "variableDefinition2"
               }
             },
           });
         }
           return next(action);
       });
   

2. Within your <script> section, call the store when you embed your agent, as in the following example where store is called just before where styleOptions is called (you must replace the BOT_ID with your ID):

   const BOT_ID = "12345-5678";
   const theURL = "https://powerva.microsoft.com/api/botmanagement/v1/directline/directlinetoken?botId=" + BOT_ID;
   
   fetch(theURL)
       .then(response => response.json())
       .then(conversationInfo => {
           window.WebChat.renderWebChat(
               {
                   directLine: window.WebChat.createDirectLine({
                       token: conversationInfo.token,
                   }),
                   store,
                   styleOptions
               },
               document.getElementById('webchat')
           );
       })
       .catch(err => console.error("An error occurred: " + err));