Create and edit topics in your Power Virtual Agents bot
In Power Virtual Agents, a topic defines a how a bot conversation plays out.
To author topics, you can customize provided templates, create topics from scratch, or get suggestions from existing help sites.
In Power Virtual Agents, a topic represents some portion of a conversational thread between a user and a chatbot. You define and work with topics on an authoring canvas. A topic contains one or more conversation nodes, which together define the conversational paths that that topic can take. Each node performs an action, such as sending a message or asking a question.
Often, a topic also has a set of trigger phrases—phrases, keywords, and questions that a customer is likely to use that are related to a specific issue. The Power Virtual Agents AI uses natural language understanding, your customer's message, and the trigger phrases for all your topics to find the most appropriate topic to trigger. The message doesn't need to exactly match a topic's trigger phrases to trigger the topic. For example, a topic about store hours might include the trigger phrase
check store hours. If a customer sends, "see store opening hours," Power Virtual Agents can still trigger your store hours topic.
Natural language understanding
The AI uses natural language understanding (NLU) to parse what a customer typed and find the most appropriate trigger phrase or node.
For example, a user might type "Open hours" into your bot. The AI matches that to the Store hours topic, begins a conversation that asks which store the customer is interested in, and then displays the hours the store is open.
The Test bot pane shows how the bot conversation plays out at every step. You can use the Test bot pane to fine-tune a topic without having to exit the Power Virtual Agents portal.
For bot and topic limits, see Quotas, limits, and configuration values.
This topic contains Power Virtual Agents preview documentation and is subject to change.
Preview features aren't meant for production use and may have restricted functionality. These features are available before an official release so that you can get early access and provide feedback.
If you're building a production-ready bot, see Power Virtual Agents Overview.
A bot can include two types of topics, system and custom. Every new bot starts with a set of system and custom topics.
System topics are ones that support essential behaviors, such as a custom request to speak to a person or end the conversation. Some system topics have trigger phrases, which you can customize to fit your bot's needs.
- You can't create system topics.
- You can't delete system topics, but you can disable them.
- You can make changes to system topics. However, until you're comfortable creating end-to-end bot conversations, you shouldn't edit the system topics.
For more information, see Use system topics.
Custom topics cover common behaviors, such as greeting a customer, ending a conversation, or starting a conversation over.
- You can make changes to the custom topics that your bot starts with or remove them from your bot entirely.
- All topics that you create are custom topics.
Create a topic
Open your bot and select Topics. On the Topics page, select + New topic.
The Trigger phrases pane should already be open. If not, select the Trigger phrases node to open it.
Under Add phrases, type a trigger phrase for your topic.
Your bot needs 5 to 10 trigger phrases to train the AI to understand your customers' responses. To add more trigger phrases, you can either:
- Select the + button.
- Paste a set of trigger phrases, each one on a separate line.
- Type a set of trigger phrases, pressing Shift+Enter after each one to place it on a separate line.
You can include punctuation in a trigger phrase, but it's best to use short phrases rather than long sentences.
Select Details to open the topic details pane.
Enter a Name for your topic and, optionally, a Description.
Use the name to identify the topic. The Topics page lists all the topics defined in your bot, by name. A customer might see the topic name if the bot can't determine which topic matches the customer's message.
The Description is never shown to users. Use it to describe the purpose of the topic for yourself and other bot makers on your team.
Select Save to save your changes and add the topic to the topics list.
Design a topic conversation path
When you create a topic, a Trigger phrases node is inserted for you. Add more nodes to control the conversation.
Open your bot and select Topics, and then select a topic.
To add a node, select Add node (+) on the line or branch between or after a node.
Select a node type to insert the node.
The following table lists the types of nodes you can insert in a topic:
|Send a message||Send the customer a message.|
|Add a condition||Branch your conversation based on a condition.|
|Set a variable value||Set a value for a new or existing variable.|
|Topic management||Redirect, transfer, or end the topic or conversation.|
|Call an action||Call a Power Automate flow.|
Add a question node
The Question node allows you to prompt a user for information and store their response in a variable for use later on in the conversation.
The node allows you to choose the type of information to collect, such as a multiple-choice answer, a prebuilt entity, or a custom entity. Question behavior properties allow you to control the behavior of the node, such as what to do when the user enters an invalid response.
Just like Message nodes, Question nodes can include images, videos, cards, quick replies, and message variations. For more information, see Send a message.
Select Add node (+), and then select Ask a question.
In the Enter a message box, type the question you want to ask.
Select the box under Identify, then either create or select an entity to determine what the bot should listen for in the user's response. Learn how to use entities in a conversation.
Depending which Identify option you selected, you may have more properties you need to set.
For example, for Multiple choice options, you need to enter the choices the user can specify in Options for user. Each choice is presented as a multiple-choice button, but users can also type their answers.
Select the box under Save response as and change the name of the default variable to something meaningful, like customerName or bookingDate.
To choose a different variable, select >, and then select a variable.
Configure question behavior
Question behavior properties allow you to control other aspects of the Question node, such as how the bot responds to an invalid response or how it validates user input.
On the Question node, select the Node Menu (⋮), and then select Properties.
In the Question properties pane, select Question behavior.
The Question behavior pane opens.
Skip behavior determines what the bot should do if the question node's variable already has a value from earlier in the conversation.
- Allow question to be skipped: Skip the question if the variable has a value.
- Ask every time: Ask the question even if the variable has a value.
Reprompt determines how your bot will react if it doesn't get a valid answer from the user. You can tell it to try again once, twice, or move on without getting an answer. To customize what your bot does when it moves on, see No valid entity found. You can also change the prompt to give the user more context.
How many reprompts: The number of times your bot tries to get a valid answer. Repeat up to 2 times is the default. You can also select Repeat once or Don't repeat.
Retry prompt: To change the message, select Customize, and then enter the new prompt.
Additional entity validation
By default, the Question node checks for a valid response based only on the entity you selected. Additional entity validation allows you to add criteria to the basic test. For example, the Question node accepts any numeric value when it identifies a number, but you might want to make sure it's less than 10. You can also change the prompt to help the user enter a valid response.
Condition: Enter a Power Fx formula that returns a boolean value (
false); for example,
Topic.Var1 < 10
Condition not met prompt: To change the message, select Customize, and then enter the new prompt.
No valid entity found
No valid entity found determines what happens when your bot stops trying to get a valid response from the user. You can escalate to a human agent or provide a default value for now. You can also change the prompt to let the user know.
Action if no entity found:
- Escalate: Redirect the user to the Escalate system topic. This is the default.
- Set variable to value: Set the output variable to a value and move on to the next node. Enter or select the value in Default entity value.
- Set variable to empty (no value): Set the output variable to
Blankand move on to the next node. You can use a Condition node later to check whether the variable has a value.
No entity found message: To change the message, select Customize, and then enter the new prompt.
Interruptions determines whether the user can switch to a different topic during the question.
- Allow switching to another topic: The user can abandon the question for a new topic.
Delete a node
Select the node's Node Menu (⋮), and then select Delete.
Controls for editing nodes on the canvas
You can use the authoring canvas toolbar to quickly rename the topic. Select the topic name in the toolbar, type the new name, and then press Enter.
You can use controls on the toolbar to cut, copy, paste, and delete the selected node or selected adjacent nodes.
The toolbar also has a control for undo. Open the Undo menu to revert all actions back to the last save or to redo the previous action.
Once you've used the Cut or Copy tools to place one or more nodes on the clipboard, there are a couple of ways to paste them in the canvas:
If you select a node and then select Paste, the nodes on the clipboard are inserted after the selected node.
If you select the Add node (+) menu and then select Paste, the nodes on the clipboard are inserted at that point.
Edit topics with the code editor
The code editor shows the topic in YAML, a markup language that's easy to read and understand. Use the code editor to copy and paste topics from other bots, even ones created by other authors.
Designing a topic entirely in the code editor and pasting complex topics isn't fully supported.
In this example, you'll copy and paste YAML into the code editor to quickly add a topic that asks the customer for shipping information.
On the Topics page, select + New topic.
In the upper-right corner of the authoring canvas, select More options (…), and then select Open code editor.
Select and delete the contents of the code editor. Then copy and paste the following YAML code:
kind: AdaptiveDialog beginDialog: kind: OnRecognizedIntent id: main intent: displayName: Lesson 3 - A topic with a condition, variables and a prebuilt entity triggerQueries: - Buy items - Buy online - Buy product - Purchase item - Order product actions: - kind: SendMessage id: Sjghab message: I am happy to help you place your order. - kind: Question id: eRH3BJ alwaysPrompt: false variable: init:Topic.State prompt: To what state will you be shipping? entity: StatePrebuiltEntity - kind: ConditionGroup id: sEzulE conditions: - id: pbR5LO condition: =Topic.State = "California" || Topic.State = "Washington" || Topic.State = "Oregon" elseActions: - kind: SendMessage id: X7BFUC message: There will be an additional shipping charge of $27.50. - kind: Question id: 6lyBi8 alwaysPrompt: false variable: init:Topic.ShippingRateAccepted prompt: Is that acceptable? entity: BooleanPrebuiltEntity - kind: ConditionGroup id: 9BR57P conditions: - id: BW47C4 condition: =Topic.ShippingRateAccepted = true elseActions: - kind: SendMessage id: LMwySU message: Thank you and please come again.
Select Save, and then select Close code editor.
Test and publish your bot
Test your bot when you make changes to your topics, to make sure that everything is working as expected.
After you've designed and tested your bot, publish it to the web, mobile or native apps, or Microsoft Bot Framework channels.
Submit and view feedback for