Defining intents

An intent is a purpose or goal expressed in a customer's input, such as answering a question or processing a bill payment. By recognizing the intent expressed in a customer's input, the Conversation service can choose the correct dialog flow for responding to it.

Planning your intents

To plan the intents for your application, you need to consider what your customers might want to do, and what you want your application to be able to handle. Choosing the correct intent for a user's input is the first step in providing a useful response. The intents you identify for your application will determine the dialog flows you need to create; they also might determine which back-end systems your application needs to integrate with in order to complete customer requests (such as customer databases or payment-processing systems).

  1. Gather as many actual customer questions, commands, or other inputs as possible. Using input from real users gives a better picture of the expected input than having experts create lists of possible utterances. Remember that customers might phrase the same kind of request in many different ways. For example, the following examples all represent requests for weather information:

    • Tell me the current weather conditions.
    • Is it raining?
    • What's it like outside?
  2. After you have a list of examples, sort them into categories based on the capabilities you want your application to support. These categories represent the intents you will define, and the examples will help your application to identify the intents in new input. As you plan your intents, keep the following guidelines in mind:

    • Do not make your intents too similar. Similar intents can be difficult for the Conversation service to distinguish. If you find that you have several intents that are close in meaning, consider whether you could combine them into a single intent, and then use entities to provide multiple possible responses for that intent.
    • Remember that a customer's input does not have to be an exact match for any of your examples; intents are recognized using natural-language processing.
  3. Continue to refine your intents and examples as needed. Do not think of your set of intents as a finished product. It is likely that when you design your dialogs, you will identify additional intents that you need to add. You can also continue to gather input from new customers and use it to add new examples; this iterative process improves your application's ability to recognize intents accurately.

Creating an intent

You use the Conversation tool to create intents. The number of intents and examples you can create in a single service instance depends on your Conversation service plan:

Service plan Intents per service instance Examples per service instance
Standard/Premium 2000 25,000
Free 25 25,000

Create some intents.

  1. In the Conversation tool, open your workspace and then select the Intents tab in the navigation bar. If Intents is not visible, use the Menu menu to open the page.

  2. Select Create new.

  3. In the Intent name field, type a descriptive name for the intent. The intent name can contain letters (in Unicode), numbers, underscores, hyphens, and periods. The name cannot consist of .. or any other string of only periods. Intent names cannot contain spaces and must not exceed 128 characters. The following are examples of intent names:

    • #weather_conditions
    • #pay_bill
    • #escalate_to_agent

    Tip: The tooling automatically includes the # character in the intent names, so you do not have to add one.

    You can select Create to save your intent name, without adding examples. You can also select the user example field, or use the tab key to move forward, and add examples.

  4. In the User example field, type the text of a user example for the intent. An example can be any string up to 1024 characters in length. The following might be examples for the #pay_bill intent:

    • I need to pay my bill.
    • Pay my account balance
    • make a payment

    If you have defined or plan to define entities that correspond to this intent, refer to them in some of the examples. Doing so helps to establish a relationship between the intent and entities.

    Important: Intent names and example text can be exposed in URLs when an application interacts with the service. Do not include sensitive or personal information in these artifacts.

    Press Enter or select + to save the example.

  5. Repeat the same process to add more examples. You can tab between each example. Provide at least 5 examples for each intent. The more examples you provide, the more accurate your application can be.

    Screen capture showing intent definition

  6. When you have finished adding examples, select Create to finish creating the intent.


The intent you created is added to the Intents tab, and the system begins to train itself on the new data.

You can select any intent in the list to open it for editing. You can make the following changes:

  • Rename the intent.
  • Delete the intent.
  • Add, edit, or delete examples.
  • Move an example to a different intent.

You can tab from the intent name to each example, editing the examples if you choose.

To move an example, select the example by selecting the check box and then select Move to.

Screen capture showing how to move an example

Importing intents and examples

If you have a large number of intents and examples, you might find it easier to import them from a comma-separated value (CSV) file than to define them one by one in the Conversation tool.

  1. Collect the intents and examples into a CSV file, or export them from a spreadsheet to a CSV file. The required format for each line in the file is as follows:


    where <example> is the text of a user example, and <intent> is the name of the intent you want the example to match. For example:

    Tell me the current weather conditions.,weather_conditions
    Is it raining?,weather_conditions
    What's the temperature?,weather_conditions
    Where is your nearest location?,find_location
    Do you have a store in Raleigh?,find_location

    Important: Save the CSV file using UTF-8 encoding, with no byte order mark (BOM).

  2. In the Conversation tool, open your workspace and then select the Intents tab in the navigation bar. If Intents is not visible, use the Menu menu to open the page.

  3. Select Import and then drag a file, or browse to select a file from your computer. The file is validated and imported, and the system begins to train itself on the new data.

    Important: The maximum CSV file size is 10MB. If your CSV file is larger, consider splitting it into multiple files and importing them separately.


You can view the imported intents and the corresponding examples on the Intents tab. You might need to refresh the page in order to see the new intents and examples.

Testing your intents

After you have finished creating new intents, you can test the system to see if it recognizes your intents as you expect.

  1. In the Conversation tool, select the Ask Watson icon.

  2. In the Try it out panel, enter a question or other text string and press Enter to see which intent is recognized. If the wrong intent is recognized, you can improve your model by adding this text as an example to the correct intent.

    Tip: If you have recently made changes in your workspace, you might see a message indicating that the system is still retraining. If you see this message, wait until training completes before testing:

    Screen capture showing retraining message

    The response indicates which intent was recognized from your input.

    Screen capture of testing intents

  3. If the system did not recognize the correct intent, you can correct it. To correct the recognized intent, select the displayed intent and then select the correct intent from the list. After your correction is submitted, the system automatically retrains itself to incorporate the new data.

    Screen capture of correcting a recognized intent

  4. If the input is unrelated to your application, you can indicate that. Select the displayed intent and choose "Mark as irrelevant". Learn more about Irrelevant input.

    Mark as irrelevant screen capture

If your intents are not being correctly recognized, consider making the following kinds of changes:

  • Add the unrecognized text as an example to the correct intent.
  • Move existing examples from one intent to another.
  • Consider whether your intents are too similar, and redefine them as appropriate.