Edit

Configure context variables for bots

  • Article

Important

Power Virtual Agents capabilities and features are now part of Microsoft Copilot Studio following significant investments in generative AI and enhanced integrations across Microsoft Copilot.

Some articles and screenshots might refer to Power Virtual Agents while we update documentation and training content.

This article lists the context variables for Azure and Copilot Studio bots, and how you can configure them in Omnichannel for Customer Service. To understand how to create context variables, see Manage context variables.

Context variables for Azure bots

The following table contains the list of context variables in Omnichannel for Customer Service that you can use for configuring Azure bots.

Context variable type Context variable name Description How to map in Azure
Pre-conversation survey Use the question type that you create in Omnichannel for Customer Service. The context variables for pre-conversation answers store the customer answers for questions in the pre-conversation survey. Use the following information to map the question type variable in Omnichannel for Customer Service with the variable type in Azure:
  • Single line: String
    • Multiple lines: String
  • Option set: String
  • User Consent: Boolean
Custom context Use the variable name that you create in Omnichannel for Customer Service or pass using the setContextProvider API. These are custom context variables that can be created and passed through the live chat SDK. Map the user's response as a JSON to use custom context variable in Omnichannel for Customer Service.
Conversation msdyn_ConversationId Use the context variable that contains the conversation ID for the ongoing conversation and can fetch and perform operations on the record in Microsoft Dataverse. String: String
Contact msdyn_contact_msdyn_ocliveworkitem_Customer Use this context variable that contains the record ID for the customer (contact) record that is linked to the conversation. Parse JSON to extract record ID
Account msdyn_account_msdyn_ocliveworkitem_Customer Use this context variable that contains the record ID for the account record linked to the conversation. Parse JSON to extract record ID
Case msdyn_incident_msdyn_ocliveworkitem Use this context variable that contains the record ID for the case record linked to the conversation. Parse JSON to extract record ID

Note

Use the context variable names as defined and don't change them when you author flows in Azure or Copilot Studio bots. Also, be sure to use exact match to pass the value to the context variable because it is case-sensitive. If there's a mismatch, the record won't get automatically identified. More information: Identify records automatically

Context variables for Copilot Studio bots

The following table contains the list of context variables available in Omnichannel for Customer Service that you can use for configuring Copilot Studio bots.

Important

To be able to use the messaging and voice variables, ensure that you first install the extension solutions.

Context variable type Context variable name Description How to map in Copilot Studio
Pre-conversation survey Use the question type that you create in Omnichannel for Customer Service. The context variables for pre-conversation answers store the customer answers for questions in the pre-conversation survey. Use the following information to map the question type variable in Omnichannel for Customer Service with the variable type in Copilot Studio:
  • Single line: User’s entire response
    • Multiple lines: User's entire response
  • Option set: User's entire response
  • User Consent: Boolean
Custom context Use the variable name that you create in Omnichannel for Customer Service or pass using the setContextProvider API. These are custom context variables that can be created and passed through the live chat SDK. Use the following information to map the custom context variable in Omnichannel for Customer Service with the variable type in Copilot Studio:
  • String: User's entire response
    • Boolean: Boolean
  • Number, Floating Number: Number
Conversation msdyn_ConversationId Use the context variable that contains the conversation ID for the ongoing conversation and can fetch and perform operations on the record in Microsoft Dataverse. String: User's entire response.
Messaging and voice variables msdyn_CustomerType Use this context variable that contains the customer type for the account or contact record that's linked to the conversation. Select the Omnichannel for Customer Service extension solution variable.
msdyn_CustomerName Use this context variable that contains the customer name for the account or contact record that's linked to the conversation. Select the Omnichannel for Customer Service extension solution variable.
msdyn_CustomerId Use this context variable that contains the customer ID for the account or contact record that's linked to the conversation. Select the Omnichannel for Customer Service extension solution variable.
msdyn_CaseId Use this context variable that contains the ID of the case record that's linked to the conversation. Select the Omnichannel for Customer Service extension solution variable.
msdyn_CaseTitle Use this context variable that contains the title of the case record that's linked to the conversation. Select the Omnichannel for Customer Service extension solution variable.
Voice-only variables CustomerPhoneNumber Use this context variable for the customer's phone number that's provided in the Telephony activity. Select the Omnichannel for Customer Service extension solution variable.
OrganizationPhoneNumber Use this context variable for the organization's phone number that's provided in the Telephony activity. Select the Omnichannel for Customer Service extension solution variable.
Extension method name va_SurveyConsent Use this dialog to determine if a customer has agreed to participate in surveys during the conversation. Use this method to escalate conversation details to Omnichannel for Customer Service.
va_CustomerLocale Use this dialog to transfer the user currently talking to the bot to another bot that can speak in a different language. Set the code by selecting the input variable and using the correct locale code.

Configure context variables for Copilot Studio bot

In Copilot Studio, do the following:

  1. On the Topics page, select New topic.

  2. On the Setup tab, enter a name and description, and save the topic.

  3. Select Go to authoring canvas.

  4. Select Add node, choose the Ask a question action.

  5. Edit the Identify field, and in the Choose information to identify dialog box, select an option that will match the context variable data type. For information on the data type mapping, see the information in the preceding table.

  6. Edit Save response as, and in the Variable Properties dialog, update the value for Name with the required Omnichannel for Customer Service context variable. Make sure Bot (any topic can access) and External sources can set values are selected. The External sources can set values option is applicable only for getting the context variable.

    Configure context variable in a topic.

  7. Save and publish the changes.

At runtime, the required information is captured in the context variable that can then be used for further actions based on the workflow you configure. The bot can set the information for the context variables to link the conversation and case when the bot escalates the conversation to an agent. More information: Link customer and case to a conversation

You can also configure the Transfer to agent node in the Copilot Studio topic to send a private message with relevant context variables to the live agent during the escalation.

The global variables that are created in Copilot Studio can be passed to Omnichannel for Customer Service when a conversation is escalated. For the complete list, see Contextual variables available upon hand off.

Parse JSON object to extract record ID

Make sure that you have the following details:

  • The Omnichannel for Customer Service context variable, such as msdyn_contact_msdyn_ocliveworkitem_Customer.
  • The schema details

A copy of the sample schema details is as follows:

        Schema: 
        {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "RecordId": {
                        "type": "string"
                    },
                    "PrimaryDisplayValue": {
                        "type": "string"
                    }
                },
                "required": [
                    "RecordId",
                    "PrimaryDisplayValue"
                ]
            }
        }

PrimaryDisplayValue will contain the value from the attribute in the Dataverse entities. The mapping for the entity attributes is as follows:

  • Cases: Case title
  • Contacts: Full name
  • Accounts: Name

Here's a sample context record.

{
    "msdyn_contact_msdyn_ocliveworkitem_Customer": [
        {
            "RecordId": "<GUID>",
            "PrimaryDisplayValue": "<FullName>"
        }
    ],
    "msdyn_liveworkitemid": "<GUID>"
}

See also

Integrate a Copilot Studio bot
Integrate an Azure bot
Configure bots to escalate and end conversations
Live chat SDK reference