Edit

Share via

Configure context variables for AI Agents

  • 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.

Note

Copilot Studio bot is renamed as Copilot agent (agent or AI agent). Human agent is now renamed as customer service representative (service representative or representative). You might come across references to the old and new terms while we update the product UI, documentation, and training content.

Applies to: Dynamics 365 Contact Center—standalone and Dynamics 365 Customer Service only

This article lists the context variables for Azure and Copilot Studio agents, 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 agents

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

Context variable type Context variable name Description How to map in Azure
Pre-conversation survey Use the pre-conversation survey question name that you create in Omnichannel for Customer Service. The system stores responses from the pre-conversation survey as context variables. Use the following information to map the question name 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. The custom context variables that you create can be passed through the live chat SDK. Map the user's response as a JSON to use custom context variable in Omnichannel for Customer Service.
Custom context for Direct Line Use the variable name that you create in Omnichannel for Customer Service The custom context variables that you create can be passed through as key-value pairs in Activity.ChannelData.ConversationContext when your DirectLine client starts a conversation. 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: 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
Channel Instance msdyn_ChannelInstanceId The Dataverse unique identifier of the Channel Instance record – for example, the unique identifier of the configured chat widget or Facebook page String: User's entire response.
Workstream msdyn_WorkstreamId The Dataverse unique identifier of the Workstream associated with the channel instance. String: User's entire response.
Channel Locale msdyn_Locale The configured locale code on your channel instance – e.g. your chat widget or Facebook page. This can be used for scenarios like multi-lingual Copilot Studio agents. String: User's entire response.
Social Profile msdyn_SocialProfileId The Dataverse record unique identifier for the social profile associated with the conversation. String: User's entire response.
Line Customer Name msdyn_LineCustomerName The customer name from the LINE API. String: User's entire response.
Teams Customer Name msdyn_TeamsCustomerName The customer name from Microsoft Teams. String: User's entire response.
Teams Customer Email msdyn_TeamsCustomerEmail The email address (UPN) from Microsoft Teams. String: User's entire response.
Apple Capabilities List msdyn_CapabilityList Apple Messages for Businesses capability list values as a delimited string. String: User's entire response.
Apple Group ID msdyn_AppleMessagesForBusinessGroupId Apple Messages for Businesses Group ID. String: User's entire response.
Apple Intent ID msdyn_AppleMessagesForBusinessIntentId Apple Messages for Businesses Intent ID. String: User's entire response.
Apple Locale msdyn_AppleMessagesForBusinessLocale Locale provided by the Apple Messages for Businesses API. String: User's entire response.
Apple Business ID msdyn_AppleBusinessId The Business ID from your Apple Messages for Business account. String: User's entire response.
Facebook Customer Name msdyn_FacebookCustomerName The customer name from Facebook. String: User's entire response.
Facebook Customer Locale msdyn_FacebookLocale The customer’s end user locale from Facebook. String: User's entire response.
Facebook Customer Timezone msdyn_FacebookTimezone The customer timezone from Facebook. String: User's entire response.
Facebook Customer Page Scoped ID msdyn_FacebookUserPageScopedId The customer’s page-specific user ID from Facebook. String: User's entire response.
Facebook Page ID msdyn_FacebookPageId The PageID from your Facebook page. String: User's entire response.
Customer Phone Number msdyn_CustomerPhoneNumber The phone number the customer is texting in from in WhatsApp and SMS channels. String: User's entire response.
Organization Phone Number msdyn_OrganizationPhoneNumber The phone number receiving messages from the customer (your organization’s number). Note this is not passed on WhatsApp via Azure Communication Services String: User's entire response.
WhatsApp Universal link message msdyn_WhatsAppCustomerFirstMessage If you are using a pre-filled message in your WhatsApp universal link, that information will be passed in this variable. String: User's entire response.

Note

Use the context variable names as defined and don't change them when you author flows in Azure or Copilot Studio agents. 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 agents

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

Important

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 pre-conversation survey question name that you create in Omnichannel for Customer Service. The system stores responses from the pre-conversation survey as context variables. Use the following information to map the question name 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 for chat Use the variable name that you create in Omnichannel for Customer Service or pass using the setContextProvider API. The custom context variables that you create can be 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
Custom context for Direct Line Use the variable name that you create in Omnichannel for Customer Service The custom context variables that you create can be passed through as key-value pairs in Activity.ChannelData.ConversationContext when your DirectLine client starts a conversation. 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-only variables msdyn_CustomerType Use this context variable that contains the customer type for the account or contact record 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 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 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 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 linked to the conversation. Select the Omnichannel for Customer Service extension solution variable.
msdyn_ChannelInstanceId The Dataverse unique identifier of the Channel Instance record, for example, the unique identifier of the configured chat widget or Facebook page String: User's entire response.
msdyn_WorkstreamId The Dataverse unique identifier of the Workstream associated with the channel instance. String: User's entire response.
msdyn_Locale The configured locale code on your channel instance, for example, your chat widget or Facebook page. This can be used for scenarios like multi-lingual Copilot Studio agents. String: User's entire response.
msdyn_SocialProfileId The Dataverse record unique identifier for the social profile associated with the conversation. String: User's entire response.
msdyn_LineCustomerName The customer name from the LINE API. String: User's entire response.
msdyn_TeamsCustomerName The customer name from Microsoft Teams. String: User's entire response.
msdyn_TeamsCustomerEmail The email address (UPN) from Microsoft Teams. String: User's entire response.
msdyn_CapabilityList Apple Messages for Businesses capability list values as a delimited string. String: User's entire response.
msdyn_AppleMessagesForBusinessGroupId Apple Messages for Businesses Group ID. String: User's entire response.
msdyn_AppleMessagesForBusinessIntentId Apple Messages for Businesses Intent ID. String: User's entire response.
msdyn_AppleMessagesForBusinessLocale Locale provided by the Apple Messages for Businesses API. String: User's entire response.
msdyn_AppleBusinessId The Business ID from your Apple Messages for Business account. String: User's entire response.
msdyn_FacebookCustomerName The customer name from Facebook. String: User's entire response.
msdyn_FacebookLocale The customer’s end user locale from Facebook. String: User's entire response.
msdyn_FacebookTimezone The customer timezone from Facebook. String: User's entire response.
msdyn_FacebookUserPageScopedId The customer’s page-specific user ID from Facebook. String: User's entire response.
msdyn_FacebookPageId The PageID from your Facebook page. String: User's entire response.
msdyn_CustomerPhoneNumber The phone number the customer is texting in from in WhatsApp and SMS channels. String: User's entire response.
msdyn_OrganizationPhoneNumber The phone number receiving messages from the customer (your organization’s number). Note this is not passed on WhatsApp via Azure Communication Services String: User's entire response.
msdyn_WhatsAppCustomerFirstMessage If you are using a pre-filled message in your WhatsApp universal link, that information will be passed in this variable. String: User's entire response.
Voice-only variables 1 CustomerPhoneNumber Use this context variable for the customer's phone number in the Telephony activity. Select the Omnichannel for Customer Service extension solution variable.
OrganizationPhoneNumber Use this context variable for the organization's phone number 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 agent to another agent that can speak in a different language. Set the code by selecting the input variable and using the correct locale code.

1 To use other context variables for voice, you can obtain them from Copilot Studio. Learn more in Work with variables.

Configure context variables for Copilot Studio agent

To have your Copilot Studio agent read context variables from Omnichannel, do the following steps:

  1. On the Topics page, select Add a topic and from blank.

  2. Enter a name for your topic (for example, "Set context variables") and save it.

  3. Add a new node to the topic, and select Variable management > Set a variable value

  4. In your new node, under Set variable select Create a new variable.

  5. Open the Variable properties pane by clicking the new variable name. In the pane, set the Variable name to match the Omnichannel context variable's name exactly (it's case sensitive).

  6. In the Reference section, select the ellipses (...) and select Get value from this node if empty. The Copilot Studio agent retrieves the variable value from this node at runtime.

  7. In the Usage section, select Global (any topic can access) and External sources can set values. Copilot Studio accepts data from Omnichannel. Close the Variable properties pane.

  8. In your node, enter a value in To value that matches the data type your agent expects. For example, if your agent expects a string, set Text(""). Copilot Studio falls back to the value that you set here if the data doesn't arrive in the conversation.

    Configure context variable in a topic.

  9. Save and publish the changes.

During a conversation, the data from the Omnichannel context variable is set in the Copilot Studio variables and can be used in the agent's logic.

The agent can also set Omnichannel context variables during a conversation. To set an Omnichannel variable from your Copilot Studio logic, make sure that your agent is using the correct variable name and set the value in the "To value" property in your variable management node. Copilot Studio hands off the variable to Omnichannel during transfer to a customer service representative. This is often used to link the conversation to a case when the agent escalates the conversation to a service representative. More information on how to link records in Omnichannel from this data: Link customer and case to a conversation

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 contains 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>"
}

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