Stories

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.

When…

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.

Then…

Once you’ve selected the input, you can define one or multiple actions to perform.

Reply

Select an existing reply or create one inline. The bot will send that reply to the user.

Save Entity

Select an entity and a slot: the value of the entity will be saved into the slot.

Set 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. “Slot1 + Slot2”. These operations are only supported for slots of type Number.

Reset Slot

Select a slot and its value will be erased.

Do

Select an action configured in the Actions section of the skill and the bot will execute it.

Continue with

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 Continue with.

Check Slot

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.

Compare Slot

Select a slot, compare it to a given value or another slot, and execute different actions accordingly. The possible cases are: equals, higher than, lower than, 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 require assistance.