Create and edit topics

In Copilot Studio, a topic defines how an agent conversation progresses.

To author topics, you can customize provided templates, create topics from scratch, or describe what you want and have AI create the topic for you.

In Copilot Studio, a topic represents some portion of a conversational thread between a user and an agent. 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 a topic can take. Each node performs an action, such as sending a message or asking a question.

Often, a topic has a set of trigger phrases—phrases, keywords, and questions that a customer is likely to use that are related to a specific issue. Copilot Studio agents use natural language understanding, your customer's message, and the trigger phrases for all your topics to find the best 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 enters "see store opening hours," this phrase triggers your store hours topic.

Prerequisites

• To create an agent, see Quickstart: Create and deploy an agent.

Natural language understanding

An agent uses natural language understanding (NLU) to parse what a customer typed and find the best trigger phrase or node.

For example, a user might type "Open hours." The agent 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 agent pane shows how the agent conversation progresses at every step. You can use the Test agent pane to fine-tune a topic without having to exit the Copilot Studio portal.

For agent and topic limits, see Quotas, limits, app registration, certificates, and configuration values.

Topics in Copilot Studio

Web app

Topic types

An agent can include two types of topics, system, and custom topics. Every new agent starts with a set of predefined system and custom topics.

• System topics 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 agent'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 complete agent experiences, we don't recommend editing the system topics.

  For more information, see Use system topics.

• The predefined custom topics cover common behaviors, such as greeting a customer, ending a conversation, or restarting conversation.

  • You can make changes to the predefined custom topics or remove them from your agent entirely.
  • All topics that you create are custom topics.

Node types

The following types of node are available:

Option	Description
Send a message	Send the customer a message.
Ask a question	Ask the customer a question.
Ask with adaptive card	Create a JSON snippet to exchange with other apps.
Author using conditions	Branch your conversation based on a condition.
Variable management	Set a value, parse a value, or clear all variables.
Manage topics	Redirect, transfer, or end the topic or conversation.
Call a flow	Call a flow like Power Automate or Excel Online, or use a connector or a plugin.
Advanced	Generative answers, HTTP requests, events, and more.

Tip

Rename nodes to make them easier to identify. Select the node's name field to update the name directly, or select the More icon (…) of the node and select Rename from the menu. You can also rename nodes in the code editor.

It's not possible to rename Trigger nodes and Go to step nodes.

Node names can be up to 500 characters in length.

Create a topic

1. Open your agent from the list on the agents page. For better visibility, close the Test your agent panel for now.

2. On the top menu bar, select Topics.

3. Select Add a topic, and select From blank.

   A Trigger node appears on an otherwise blank topic authoring canvas.

4. Select the More icon (…) of the Trigger node, and then select Properties. The On Recognized Intent properties panel appears.

5. In the On Recognized Intent properties panel, select the Phrases area. The Phrases secondary panel appears.

6. Under Add phrases, enter a trigger phrase for your topic.

   Your agent 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 Add icon next to the text field, and enter the desired phrase.
   • Paste a set of trigger phrases, each one on a separate line, and select Enter.
   • Type a set of trigger phrases, pressing Shift+Enter after each one to place it on a separate line, and select Enter.

   You can include punctuation in a trigger phrase, but it's best to use short phrases rather than long sentences.

7. Select Details on the toolbar to open the Topic details panel.

8. Add your agent topic details:

   • Enter a name to identify the topic, such as "Store hours." The Topics page lists all the topics defined in your agent, by this name.
   • If desired, enter a display name to show to the customer when the agent can't determine which topic matches the customer's message.
   • If desired, use the Description field to describe the purpose of the topic for yourself and other agent makers on your team. Customers never see topic descriptions.

9. Select Save on the top menu bar to save your topic.

Important

Avoid using periods (.) in your topic names. It isn't possible to export a solution that contains an agent with periods in the name of any of its topics.

Design a topic conversation path

When you create a topic, a Trigger node automatically appears on the authoring canvas. You can then add different types of nodes to achieve the desired conversation path for your topic.

To add a node after another node or between two nodes on your topic authoring canvas:

1. Select the Add node icon below the node under which you want to add a new node.

2. Select the desired node type from the list that appears.

   

Delete a node

Select the More icon (…) of the node you want to delete, and then select Delete.

Controls for editing nodes on the canvas

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 to undo an edit. Open the Undo menu to revert all actions back to the last save or to redo the previous action.

Paste nodes

Once you use the Cut or Copy tools to place one or more nodes on the clipboard, there are two 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 "+" to see the Add node menu, then select Paste, the node on the clipboard is inserted at that location.

Add input and output parameters for a topic

Topics can have input and output parameters. When a topic redirects to another topic, you can use these parameters to pass information between the topics.

Additionally, if your agent uses generative mode, it can automatically fill topic inputs from the conversation context, or after generating questions to gather values from users. This behavior is similar to how generative slot filling works for actions.

To learn more about input and output parameters for topics, see Manage topic inputs and outputs.

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 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 + Create > From blank.

2. In the upper-right corner of the authoring canvas, select More, then select Open 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. The Question node now has many conditions to the question about shipping.

   

Test and publish your agent

Test your agent when you make changes to your topics, to make sure everything works as expected.

After you design and test your agent, publish it to the web, mobile or native apps, or Microsoft Bot Framework channels.

Classic

Use system and sample topics

When you create a bot, several topics are created for you.

These automatically created topics fall into two categories:

• Lesson topics help you understand simple to complex ways to use nodes to create bot conversations.

  You can edit lesson topics or delete them entirely.

• System topics are topics you're likely to need during a bot conversation.

  You can't delete or disable system topics or edit their trigger phrases. However, you can customize the nodes on the authoring canvas. We recommend that you don't customize these topics until you're comfortable creating an end-to-end bot conversation.

Create a topic

1. From the navigation menu, select Topics, then + New topic, then From blank.

   The Trigger phrases pane opens.

2. Add several trigger phrases for your topic in the Add phrases section.

   

   You can specify more than one trigger phrase for a topic, using a new line for each phrase. You can include punctuation in a trigger phrase, but it's best to use short phrases rather than long sentences.

3. In the top bar, edit the title of your topic to give it a name.

   

4. Press Enter or select the Save icon to save your changes.

5. Select the Details icon. Here you can alternatively edit the Name and add a Display name and Description.

   The Display name tells the bot which topic the person is asking about.

   The Description describes the purpose of the topic for yourself and other bot makers. This description isn't shown to users.

   

6. Select Save to add the topic to the topics list.

Design the topic's conversation path

1. In the topic list, select the topic you want to edit. You see the topic's trigger phrases. Here you define the conversation path between a customer and the agent.

   For existing or system topics, several nodes are created automatically. You can edit these nodes just as you would edit other nodes.

   When you create a new topic, a Trigger node and a blank Message node are inserted for you.

2. To add a node, select "+", Add node, located between or after nodes.

   

3. To change the paths between nodes, drag the small circle on top of the node—its node anchor—to a new location in the canvas. The dotted line represents the original path.

   

Insert nodes

When you add a node after the Trigger Phrases node or between Message nodes, you can:

• Ask a question
• Call an action
• Show a message
• Redirect to another topic
• End the conversation

Ask a question

1. Select the Ask a question option of the "+" Add node menu to add a new Question node. A question node appears.

   

2. Enter the question phrase in the Ask a question field.

   For example, if the user wants to know store hours, the bot's question might be Which store location do you need?

3. Under Identify, select an option for the user's response, such as Multiple choice options.

   This option determines what the bot should listen for when the user responds. For more information, see Use entities in a conversation.

4. Under Options for user, enter expected responses to the bot's question.

   For example, if you chose Multiple choice options in Identify, the options might include store locations such as Seattle, Bellevue, or Kirkland.

   

   Each choice is presented to the user as a multiple choice button in the chat, but users can also type their answer.

5. (Optional) Save the user response in a variable to be used later.

The conversation editor creates separate paths in the conversation depending on the customer's response. The conversation path leads the customer to the appropriate resolution for each response. You can add nodes to create branching logic, and specify what the bot should respond with for each path or variable.

Call an action

To call Power Automate flows and insert authentication nodes, select Call an action from the "+" Add node menu.

If voice-based capabilities are enabled for your bot, you see more actions.

Show a message

1. To specify a response from the bot, select the "+" Add node to add a node, and then select Show a message to add a new Message node.

2. Enter the message you want the bot to say in the text box.

   You can apply some basic formatting, such as bold, italics, ordered and unordered lists, and hyperlinks. You can also use variables that you define elsewhere in your bot conversation.

Redirect to another topic

1. To have the bot move to a different topic, select the "+" Add node to add a node, and then select Redirect to another topic. A list of topics appears.

2. Select the topic the bot should divert to. For example, you might send the user to a topic about the closure of a store if they ask about the store's hours.

   

The redirected topic is a subtopic.

You can insert more nodes under the subtopic's node.

When the conversation path for the subtopic is finished, the bot returns to the original topic. The bot then follows the nodes that are under the subtopic's node.

If you redirect to any of these system topics, however, the entire conversation ends.

• End of Conversation
• Confirmed Success
• Confirmed Failure
• Goodbye
• Escalate
• Start over (also resets any global variables)

End the conversation

When the conversation ends, you can have a survey ask users if their question or issue was answered or resolved. The response is collected on the customer satisfaction analytics page.

You can also have the conversation handed over to a live agent if you're using a suitable customer service portal, such as Omnichannel for Customer Service.

At the end of a response that resolves the user's issue or answers the question, add an End the conversation node.

• To end with a customer satisfaction survey, select End with survey.

• To insert a handoff node that links with your configured handoff product, select Transfer to agent.

  (Optional) Enter a private message to the agent.

  

Add a condition

1. To add branching logic based on variables, select the "+" Add node to add a node.

2. Select Add a condition.

3. Select Branch based on a condition.

4. Select the variable that determines whether the bot conversation should branch at this point.

   For example, if you set up user authentication, you might want a different message if the user is signed in.

Delete nodes

Select the menu icon (⋮) of the node you want to delete, and then select Delete.

Test and publish your bot

Test your agent when you make changes to your topics to ensure everything works as expected.

After you design and test your bot, publish it to the web, mobile or native apps, or Microsoft Bot Framework channels.

Teams

Design the topic's conversation path - Teams

1. In the topic list of your agent, select the topic you want to edit. For example, you might want to edit the topic Store Hours.

   

   Once open, you see the topic's trigger phrases. This authoring canvas is where you define the conversation path between a customer and the bot.

   When you create a new topic, a Trigger Phrases node and a blank Message node are inserted for you.

   For existing or system topics, several nodes are automatically created with each new topic. You can edit these nodes if needed.

2. You can add more nodes by selecting "+" Add node between nodes or after a node.

   

3. To change the paths between nodes, drag the node anchor—a small circle on top of the node. You see a dotted line indicating the original path.

   

Insert nodes - Teams

When adding a node to a trigger phrases node, choose from five different options:

• Ask a question
• Call an action
• Show a message
• Redirect to another topic
• End the conversation

If you want to redirect a topic, you can go to another topic.

Ask a question - Teams

1. Select the Ask a question option of the "+" Add node menu to add a new Question node. A question node appears.

   

2. Enter the question phrase in the Ask a question field.

   For example, if the user wants to know store hours, the bot's question might be Which store location do you need?

3. Under Identify, select an option for the user's response, such as Multiple choice options.

   This option determines what the bot should listen for when the user responds. For more information, see Use entities in a conversation.

4. Under Options for user, enter expected responses to the bot's question.

   For example, if you chose Multiple choice options in Identify, the options might include store locations such as Seattle, Bellevue, or Kirkland.

   

   Each choice is presented to the user as a multiple choice button in the chat, but users can also type their answer.

5. (Optional) Save the user response in a variable to be used later.

The conversation editor creates separate paths in the conversation depending on the customer's response. The conversation path leads the customer to the appropriate resolution for each response. You can add nodes to create branching logic, and specify what the bot should respond with for each path or value.

Add a condition - Teams

On some node types, you can add a condition.

1. To add branching logic based on variables, select the "+" Add node menu, then select Add a condition to add a new node. A couple of condition nodes appear.

2. Choose the variable you want to use to determine if the bot conversation should branch at this point.

   

Call an action - Teams

You can call Power Automate flows by selecting Call an action in the "+" Add node menu.

Show a message - Teams

A message can specify a response from your bot to the user.

1. Select the "+" Add node menu, then select Show a message to add a new Message node.

2. Enter what you want the bot to say in the text box. You can apply some basic formatting, such as bold, italics, ordered and unordered lists, and hyperlinks.

   You can also use variables that you defined elsewhere in your bot conversation.

End the conversation - Teams

You can choose to End the conversation as a final node to your bot's conversation.

There are two options:

• End with survey shows a survey that asks the user if their question or issue was answered or resolved correctly. This information is collected under the customer satisfaction analytics page.

  

• Transfer to agent allows you to type a private message to an agent that initiates their contact with the user.

Redirect to another topic - Teams

To automatically have the bot move to a separate topic, select Add node (+) to add a node, and then Redirect to another topic.

In the flyout menu, select the topic the bot should divert to. For example, you might want to send the user to a specific topic about the closure of a store if they ask about store hours for that store.

When the bot goes to another topic, the bot goes through the conversation path for that topic and then returns to the original topic—the place where it left.

You can consider the redirected topic as a subtopic.

If you redirect to any of the following system topics, however, the entire conversation ends:

• Start over (resets any global variables)
• Escalate
• End of Conversation
• Confirmed Failure
• Confirmed Success
• Goodbye

Use variables

You can use variables that you defined elsewhere in your bot conversation.

Delete nodes - Teams

Select the menu icon (⋮) of the node you want to delete, and then select Delete.

Test and publish your bot - Teams

After you make changes to your topics, Test your agent to ensure everything is working as expected.

Once you finish designing and testing your bot, you can publish it, so other team members can use it.