Intents

An intent represents a mapping between what a user says and what action should be taken by your software.

Intent interfaces have the following sections:

  • User says
  • Action
  • Response
  • Contexts

User Says

Example (“) and Template (@) Modes

Each User says expression can be in one of two modes: Example Mode (indicated by the " icon) or Template Mode (indicated by the@ icon).

Examples are written in natural language and annotated so that parameter values can be extracted. You can read more on annotation below.

Templates contain direct references to entities instead of annotations, i.e., entity names are prefixed with the @ sign.

To toggle between modes, click on the " or @ icon.

We recommend using examples rather than templates, because it’s easier and Machine Learning learns faster this way. And remember: the more examples you add, the smarter your agent becomes.

Example Annotation

Annotation is a process (and also the result of such process) of linking a word (or phrase) to an entity.

Automatic Annotation

When you add examples to the ‘User says’ section, they are annotated automatically. The system detects the correspondence between words (or phrases) and existing developer and system entities and highlights such words and phrases. It also automatically assigns a parameter name to each detected entity.

Editing Automatically Annotated Examples

You can edit the linked entity and the parameter name assigned to it in either the review window that opens when you click on the annotated example, or the parameter table of the ‘Action’ section.

The results of the automatic annotation in the review window and parameter table are synchronized. If you change something in the review window, the respective changes will automatically occur in the parameter table, and vice versa.

Note that changes made in the review window and in the parameter table have different scopes:

  • Changes in the review window won’t affect other examples containing the same annotations.
  • Changes in the parameter table will affect all ‘User says’ examples with the same annotation.

You can do 3 type of changes:

  • Assign a different entity to an annotated part of the example
  • Edit the parameter name
  • Delete the annotation (i.e., delete the link between the word and the entity).

Local changes (in one example)

  • To assign a different entity to the annotation in one example, click on the highlighted phrase. A pop-up window will appear, where you can choose from the list of existing system or developer entities.
  • In order to change a parameter name in one example, click on the example and edit the parameter name in the review window.
  • To delete the annotation, click on either the bin icon in the pop-up window or the x icon of the corresponding row in the review window.

Changes for entire intent (in the parameter table)

  • To assign a different entity to the parts highlighted with the same color in all examples, click on the entity in the parameter table. In the pop-up window, choose from the list of the existing system or developer entities.

  • To change the parameter name for the annotations through all examples, edit the parameter name in the parameter table.

  • To delete a particular annotation from all examples, click on the menu icon on the right side of the respective row in the parameter table and select ‘Delete’ from the drop-down menu.

Manual Annotation

If necessary, you can annotate examples manually by selecting a word or phrase and choosing an existing entity or creating a new one in the pop-up window.

Search Option

If you need to find a specific example or template, you can search for keywords in the User says section.

Action

This section consists of the action name field and the parameter table.

The action name is defined manually. It will be the trigger word for your app to perform a particular action.

Parameters can be filled in automatically from the ‘Users says’ examples and templates, or added manually.

Read more in Action and Parameters.

Response

In this section, you can define your agent’s responses which will be provided by your application when the intent is triggered.

Text Response

You can improve your agent eloquence by adding several variations of the text response per intent. When the same intent has been triggered more than once, different text response variations will be unrepeatable until all options have been used. It'll help make your agent speech more human-like.

References to Parameter Values

Responses can contain references to parameter values.

If a parameter is present in the parameter table, use the following format to refer to its value in the ‘Text response’ field: $parameter_name.

There are special parameter value types that don’t appear automatically in the parameter table.

If you need to refer to such a special type of value, you'll have to add a new parameter to the parameter table, define its value manually, and then reference it in the response as $parameter_name.

Use the following formats:

  • $parameter_name.original – to refer to the original value of the parameter

  • $parameter_name_for_composite_entity.inner_alias – to refer to a value of one of the composite entity components

  • #context_name.parameter_name – to reference a parameter value collected in some other intent with defined context

Special Characters

If you need the dollar sign $ or the number sign # to appear in your agent's text response, use braces around the value that follows $ or #. For example: ${100} – where 100 is a constant value ${$number} – where $number is a reference to the parameter value #{channel} – where channel is a string #{#channel.name} – where #channel.name is the reference to the parameter value "name" from the context "channel"

If you need to use braces in text responses, use double braces: {{ will be displayed as { and }} will be displayed as }.

Handling Empty Parameter Values

If an intent is designed in such a way that some parameters can return empty values after the intent has been triggered, the variants of Text response that contain references to the parameters with empty values won't be given as text responses. Make sure to define different variations of Text response for such intents.

For example, if an intent has 2 parameters and may return both or any of them with empty value, and you want to reference parameter values in Text response, make sure to define at least 4 variants of Text response:

  • referencing both parameter values,
  • referencing the 1st parameter value,
  • referencing the 2nd parameter value,
  • without any reference to the parameter values.

Emojis

If you want your agent to display emojis in responses, just copy and paste a desired emoji in the Response field.

Rich Messages

If you use one of the following one-click integrations – Facebook Messenger, Kik, Slack, or Telegram – you can define your bot responses as rich messages (images, cards, quick replies etc.) directly in intents.

For more information, please read the documentation on Rich Messages.

Contexts

Contexts are designed for passing on information from previous conversations or external sources (e.g., user profile, device information, etc). Also, they can be used to manage conversation flow.

To define the contexts, click on ‘Define contexts’ right below the intent name.

Input contexts serve as a prerequisite for the intent to be matched; i.e., the intent will participate in matching only when all the contexts in the input context field are active.

Read more on contexts.

Intents priority

Intent priority allows you to assign more weight to one of the intent in case an input phrase matches multiple intents. Intents priority can be changed by clicking on the blue (default) dot on the left of the intent name and selecting the priority from the drop-down menu.

Fallback Intents

Fallback intents are triggered if a user's input is not matched by any of the regular intents or enabled built-in Small Talk.

When you create a new agent, a default fallback intent is created automatically. You can modify or delete it if you wish.

If you’d like to create contingency actions or responses for various input contexts, you can add your own fallback intents. Make sure to set a unique set of input contexts for each fallback intent.

To add a new fallback intent:

  • Go to Intents from the left side menu
  • Click on the tree dot “more options” menu next to ‘Create Intent’
  • Choose ‘Create Fallback Intent’

Fallback intents can reference parameter values from context directly in the ‘Text response’ field in this format: #context_name.parameter_name. See example below.

If you’d like certain phrases and their variations to be classified as a fallback intent, you need to create a regular intent, add those phrases to the ‘User says’ section, and define the same action and Text response as in the fallback intent.

Referencing Parameter Values in Fallback Intents

The following example shows how to use parameter values from context in the fallback intent.

First, we create a regular intent, ‘Greetings’, and collect the user’s name in the parameter ‘user-name’ using the slot filling feature. We also define an output context ‘greetings’ to store the parameter value.

Then, we make some modifications in the Default Fallback Intent which was automatically created with the agent. We’ll reference the user’s name as #greetings.user-name in the Text response variations. To keep the ‘greetings’ context alive, we add it as an output context to this intent as well.

Now, any input other than greetings will be classified as Default Fallback Intent.

Follow-up intents

Natural human dialogs are filled with follow-ups and confirmations, for example:

User: Get me a cab.
Agent: Your cab can meet you at the corner of 5th and Broad street in 12 mins.
User: Ahh, can you repeat that please?

or

User: I want 2 hamburgers and one Cola.
Agent: Do you want fries with that?
User: Sure, sounds good, thanks

Follow-up intents make these types of natural conversation flows easy to build and customize. With this feature of API.AI you can define dialog situations that may follow any given “parent” intent you are currently working on.

While you can also do this (and much more) by manually defining contexts, follow-up intents make the process of building sample dialogs easier and more visual. We’ve thought of most popular follow-up scenarios and taken care of building the contexts for you automatically.

Adding a Follow-up Intent

To start building Follow-up intents, go to the ‘Intents’ page, hover the mouse over intent names, tap “Add follow-up intent” link.

Select one of the available follow-up intents:

Follow-up intents are nested under parent intents which makes it easier to see your agent conversation structure. To see the follow-up click on the arrow next to the parent intent. You can nest multiple follow-up intents under one another if your use case requires.

Working with Follow-up Intents

Follow-up intents are like any other intent in API.AI: you can edit their expressions, responses, and fulfilment methods. See our documentation on intents for more information about the actions you can perform.

Follow-ups as Fallback Intents

A follow-up intent can act as a fallback if no other expression with the parent context is triggered. This can be used for handling unexpected user input. For more information about how to use fallbacks in our documentation.

Reference of Follow-up intents available

Follow-up intent name Description Sample expressions
custom Write in your custom expressions. N/A
fallback Fallback if no other expression is triggered. N/A
yes Common expressions to capture an affirmative response.

"yes"

"do it"

"sure"

"exactly"

"confirm"

"of course"

"sounds good"

"that's correct"

"I don't mind"

"I agree"

no Common expressions to capture a negative response.

"no"

"don't do it"

"definitely not"

"not really"

"thanks but no"

"not interested"

"I don't think so"

"I disagree"

"I don't want that"

later Common expressions to do something later.

"later"

"not yet"

"ask me later"

"not "

"next time"

"I said later"

"some other time"

"do it later"

"not at the moment"

"not at this time"

cancel Common expressions to cancel an action or exit.

"cancel"

"stop"

"dismiss"

"skip"

"forget that"

"stop it"

"never mind"

"do nothing"

"just forget about it"

"cancel that"

more Common expressions to get more information or manage lists.

"more"

"more results"

"anything else"

"other results"

"what else"

"are there more"

"tell me more"

"show me more"

"more information"

next Common expressions to manage lists or select items.

"next"

"next page"

"go forward"

"show me next"

"following result"

"switch to the next"

"go to the next page"

"read the next results"

"show me the next page"

"show me the following results"

previous Common expressions to manage lists or select items.

"back"

"previous"

"go back"

"previous page"

"previous results"

"return to the previous"

"return to previous page"

"go to the previous page"

"go back to previous results"

"read out the previous results"

repeat Commons expressions to repeat or do something again.

"repeat"

"repeat it"

"come again"

"do it again"

"say it again"

"say the same again"

"please repeat that"

"repeat these results"

"could you repeat that"

"repeat what you've just said"

select.number Common expressions to manage lists or select items.

"second"

"I choose number 3"

"see 1 2 3 4 and 5"

"number 4 5 7 and 8"

"select the first one"

"show me the second one"

"choose 1st and 2nd one"

"choose numbers 1 2 3 and 5"

"the 1st one and the 2nd one"

"I select number 2 and number 5"

Batch operations with intents

To copy or move intents into another agent, go to ‘Intents’ in the left hand menu and hover the mouse over the intent list. You’ll see checkboxes on the left of the intent names. Check one of them to enable the batch operations tool. Then select the intents you want to copy or move to another agent. If you need to copy or move all intents, select the checkbox at the top of the list. Once all the desired items are selected, click ‘COPY’ or ‘MOVE’.

Choose the destination agent from the drop down list. This will list all of the agents in your account in the alphabetical order.

Check any additional options you’d like to perform as part of the copy or move and click ‘START’.

Batch operation options for intents include:

  • Copy related entities – This is generally an option you want to check, as it will also copy or move over entities related to the intents being copied or moved.
  • Overwrite entities – This option will overwrite entities with the same name.
  • Overwrite intents – This option will overwrite intents with the same name.

When all selected intents are copied/moved, you can either go to the destination agent by clicking ‘PROCEED TO AGENT’ or stay in the current agent by clicking ‘DONE’.

To delete multiple intents, enable the batch operations tool by hovering the mouse over the intent list and checking one intent. Then select additional intents you want to delete. If you want to delete all of the intents, check the checkbox at the top of the list. Once all of the desired items are selected, click ‘DELETE’. You will be asked to confirm this action by clicking the ‘DELETE’ button.

Download and Upload Intents

Download Intents

You can download intents in JSON format. To do so, go to Intents from the left side menu, move the cursor over the intent, and click the little cloud sign.

Upload Intents

You can upload intents as JSON files. To do so, click on the More options button next to the Create Intent button, choose Upload intent, and follow the instructions on the page.