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.

Prerequisites

Topic types

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

  1. Open your bot and select Topics. On the Topics page, select + New topic.

    Screenshot of the Power Virtual Agents navigation pane with Topics and the New topics button highlighted.

  2. The Trigger phrases pane should already be open. If not, select the Trigger phrases node to open it.

    Screenshot of the topic authoring canvas with Trigger phrases highlighted.

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

  4. Select Details to open the topic details pane.

    Screenshot of the topic authoring canvas with Details highlighted.

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

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

  1. Open your bot and select Topics, and then select a topic.

  2. To add a node, select Add node (+) on the line or branch between or after a node.

    Screenshot of the Add node button in the Power Virtual Agents authoring canvas.

  3. Select a node type to insert the node.

The following table lists the types of nodes you can insert in a topic:

Option Description
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.

Screenshot of node types to insert after a Trigger Phrases node.

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.

  1. Select Add node (+), and then select Ask a question.

    Screenshot of a new Question mode.

  2. In the Enter a message box, type the question you want to ask.

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

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

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

    Screenshot of a new variable created for a Question node.

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.

  1. On the Question node, select the Node Menu (), and then select Properties.

  2. In the Question properties pane, select Question behavior.

    Screenshot of properties pane.

    The Question behavior pane opens.

    Screenshot of the Power Virtual Agents Question behavior pane.

Skip behavior

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

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 (true or 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 Blank and 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

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.

Screenshot highlighting the Node Menu button and the Delete button.

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.

Screenshot of the topic authoring canvas with the topic name highlighted.

You can use controls on the toolbar to cut, copy, paste, and delete the selected node or selected adjacent nodes.

Screenshot of the toolbar controls for editing nodes on the authoring canvas.

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.

Screenshot of the Undo menu.

Paste nodes

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.

Important

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.

  1. On the Topics page, select + New topic.

  2. In the upper-right corner of the authoring canvas, select More options (), and then select Open code editor.

    Screenshot of how to open the code editor.

  3. 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.
    
  4. Select Save, and then select Close code editor.

    Screenshot of a conversation created from YAML in the Power Virtual Agents 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.