Contextual Entities with IBM Watson Assistant

Simon Burns
IBM watsonx Assistant
3 min readSep 12, 2018


IBM Watson Assistant has recently introduced a new feature called Contextual Entities, and we are going to build a simple bot to show it in action. If you are not familiar with Watson Assistant you may want to read Getting Chatty with IBM Watson first.

Entities are used for identifying interesting parts of the user’s utterance, such as names and dates. Watson Assistant already provides system entities (for date, time, names, etc), and lets you define entities with synonyms and fuzzy matching, as well as defining pattern-based entities.

Now you can define entities based on their context in the utterance. You do this by annotating the entities in your intent examples. Watson will use these annotations to learn how to identify the entity values and can match new values that have not been explicitly annotated.

To illustrate the use of contextual entities we are going to build a bot that keeps a To Do list.

What’s your intent?

First we need to define an intent for adding a task, by adding a number of examples of how people might add a task.

Adding a contextual entity

To add contextual entity all you need to do is select the relevant text in each of your intent examples. When you select a section of text, a pop up will appear allowing you to add it to an entity. Once defined, the entities will be highlighted in the examples, as in the screenshot above.

If you look at the entities page, you can see the annotations, and the intents they were annotated in:

Remember the entity values are not limited to those listed here. Based on these annotations Watson will learn to find other values for the entity.

Building the dialog

To handle adding tasks, we can build a simple dialog. The #add-todo node below clears the $task variable (so that it’s always empty ready for the new task) and then skips to the true node to record the task.

The true node contains some slots to capture the @task contextual entity and optionally date and time if mentioned.

Then we add the task to the tasks list ($tasks is initialized to [] in the welcome node).

The full value expression looks like this:

<? $tasks.append({task:$task, due_time:$time, due_date:$date, created:now()}) ?>

And then we respond to confirm the task has been added:

Let’s see it in action

Now we can try it out and see that it picks out the tasks:

And then

So now we have a basic To Do bot using contextual entities. We could now enhance the bot by adding other capabilities such as listing or removing tasks.

Hopefully this has given some insight into contextual entities , and you are going off to build something with them straight away!

Find more of my Watson articles in the Conversational Directory.