A story defines how a bot should react to a given input. Each story is composed of one or multiple story parts that are supposed to happen sequentially.
Whenever a bot receives some input, it will look for the story part that matches the situation the best (
When…) and execute the corresponding actions (
Then…). If no appropriate story part is found, the bot will reply with its configured fallback message. If more than one story part matches the current context equally, one will be chosen at random.
The algorithm to pick the best story part takes into account the input (recognized intent and entities, or trigger) as well as the context (which story parts were executed before this one), in a way similar to how humans would think. In case of ambiguity, it will favor the current conversation over jumping to another topic.
Each story part starts with the expression
When, and has to be associated to a particular input. It indicates for which input this story part should be chosen and executed by the bot. The input selection menu will show all the intents and triggers defined in the Inputs section of the skill.
If an intent is chosen, it is possible to select entities as well. An entity can be marked as mandatory (
with…) or optional (
and maybe…). If mandatory, the story part will be chosen only if the entity was extracted. If optional, the story part may be chosen even if the entity is missing. It is possible to select multiple entities.
Once you’ve selected the input, you can define one or multiple actions to perform.
Select an existing reply or create one inline. The bot will send that reply to the user.
Select an entity and a slot: the value of the entity will be saved into the slot.
Select a slot and enter the value you want to set for that slot. The new value can be set from or include another slot, and you can even write formulas to add or substract slots e.g. “
Slot2”. These operations are only supported for slots of type
Select a slot and its value will be erased.
Select an action configured in the Actions section of the skill and the bot will execute it.
Select a trigger and the story part handling this trigger will be executed immediately after this one. This is useful when you have some common logic and you don’t want to repeat it in multiple stories: you can centralize it into a single story and run it using
Select a slot and execute different actions depending on the value of the slot. This is the equivalent of
if conditions in programming.
The possible conditions are:
- has value: if the slots has the given value
- is defined: if the slot has some value (whatever the value)
- is missing: if the slot is empty
The example below demonstrates the following logic: when receiving the intent
ask for headlines, execute the action
Get the news, then check the value of the slot
link. If the slot is empty, reply
Sorry, but I couldn’t find anything. If the slot has a value, reply a message containing the link.
Select a slot, compare it to a given value or another slot, and execute different actions accordingly. The possible cases are:
higher than or equal and
lower than or equal.
Sequential vs Conditional
Story parts are supposed to be executed sequentially, one after the other. Sometimes though, you expect the user to reply by some input OR some other input. To express this kind of condition, you can use the right arrow
> next to the
When clause to indent a story part one level to the right. When story parts are indented, the bot will only expect one of them to happen instead of all of them.
The example below shows that after receiving the trigger
water check, we expect either the intent
Yes or the intent
No but not both.
Timeouts and Retries
It is possible to react if the user does not respond to a given story part within a certain amount of time. The initial story part can then be repeated any number of times, and another action can be executed as a fallback.
To setup a timeout, select the timer icon at the bottom left of a story part. You can then select how long to wait, how many times to repeat the story part, and what action to execute if the user still hasn’t replied despite all the retries.
The example below shows that if the user doesn’t reply, the bot will repeat
Can you reach the water? every 30 seconds up to 3 times, and then trigger