Pass Parameters to Copilot Studio Bot from Calling Site
When building a Copilot there are times when we need to be able to pass context to the Copilot to improve the user experience by passing data that could be helpful in greeting the customers or retrieving customer information ahead of time. Microsoft has provided some documentation on how to accomplish this when building Copilots using Copilot Studio. Let's look at how we can implement this with an example.
Configuring Global Variables as Parameters
Note: The original method described below still works but it's easier to use the above approach
To configure a global variable that we can use as a parameter we need to define it in a Topic. I have a simple demo Copilot created and added a blank topic where I can set the variable value to some random value that will never get assigned. Currently this is the only way I could find in defining a global variable that will only be used to get data into the Copilot during the startup. Ideally if we have a way to just declare a global variable without having to set a value that would be cleaner. Here are the steps in detail.
I'm just going to call this Topic, Parameter Config and set the trigger to empty.
Let's create a new variable name and edit the properties after it's created by clicking on the variable. Make sure to check External sources can set values.
Similarly, I'm going to create another variable called issueType. This would be useful in situations where we want to apply branching logic and show context aware actions based on the issue or any criteria that applies to the Copilot use case.
Our Topic would look like below once everything is configured. The variable value doesn't matter, and we can set it to anything.
Let's save our Topic. We can now use these variables as parameters and expose them appropriately or use them as needed within the Topic to either apply branching logic or just display the value.
Next, I am going to update the system Conversation Start Topic to modify the initial greeting message and display the user's name and also apply branching criteria.
I have already created another Topic called Activation and going to start this Topic based on the issueType.
My Activation Topic is configured as below.
I have saved all the changes and published our Copilot. Let's enable the authentication settings to use it in the channels. This step is optional depending on your use case.
Configure Manual Authentication
Depending on the use case we might sometimes need to configure Authentication for the Copilot to perform actions that return private or sensitive data. This is very straightforward to setup under the Authentication section (Settings->Security). Microsoft also has documentation that explains this in detail.
I have configured my authentication as below.
Using Copilot in Custom Website
Now that we have configured the settings, let's go the Custom website (Settings-> Channel) section to get the URL to the Copilot.
I copied the above URL and included the global variables as query parameters we have configured in our Copilot as below.
https://copilotstudio.microsoft.com/environments/{ENV_ID}/bots/{BOT_SCHEMA_NAME}/webchat?__version__=2&name=Joe&issueType=activation
Now if we open this URL, we will see the below page that requests us to Login when using authentication. If we do not have the authentication enabled, we will not see the login prompt.
After the login, we should now see our bot displaying the name we passed in the URL and also branching the logic using the issueType parameter.
Hopefully this gave you some ideas on how you could leverage global variables to provide context-based actions at the start of your Copilot. Let me know your thoughts in the comments below.