The theory behind Narratory

Narratory is based on many years or leading research in dialog systems at the speech department of KTH - the Royal Technical University in Stockholm.

Dialog turns

Narratory (unlike most if not all other creation tools for conversational apps) takes a turn-based approach to dialog. With this, we mean that in any chat - the bot OR the user are having the turn - i.e is speaking. A dialog can then be modelled using these turns.

As an analogy, think of a theatre play. If you were in charge of writing the dialog for a play you would likely sit down and write a script similar to the below (as opposed to drawing a diagram or flow-chart):

Actor 1: Hello there
Actor 1: how are you doing?
Actor 2: Oh, it's been a long day
Actor 1: Oh, why is that?
Actor 2: Oh, I have been struggling with various flow-chart based models for dialog.
Actor 1: Oh, tell me about it. Once it grows beyond a simple prototype, it just becomes spaghetti.

The turn is here passed between the two actors, but not always immediately. Sometimes one actor keeps the turn for two turns, i.e two utterances, before passing it over (or the other actor taking the turn). In graphical chat, this is commonly done with dividing messages in several message bubbles.

In real dialog - unlike a theatre play - the direction of the dialog is of course not linear since users are not following scripts. This poses the biggest challenge in dialog design - the fact that you can never be certain what users might say.

How would the script above be written if we take this into account? Most tools take a flow-chart based approach here, with system utterances as nodes and user responses as connectors. We chose a different approach, described below:

Bot initiatives

Let's start by reviewing a slightly more syntactic version of the above dialog showing some branching using intendation:

Bot: Hello there
Bot: How are you doing?
User: Oh, it's been a long day.
Bot: Oh, why is that?
User: Oh, I have been struggling with flow-chart models for dialog.
Bot: Oh, yeah. Once it grows beyond a simple prototype, it becomes spaghetti.
User: It was great!
Bot: Oh really, I'm so glad to hear. Myself, I'm cooking here. Do you like pasta?
User: Yeah, especially lasagna
Bot: Oh yeah, lasagna is great
User: No
Bot: Right, well you aren't invited to this feast anyway
Bot: Do you want to hear more about Narratory?
User: Yeah
Bot: Sweet. It's a framework built for dialog designers, by dialog designers.
User: No
Bot: Ok, no problem!

Here, indentation is used to mark when the turn is passed from the Bot to the User. This is a fundamental part of the dialog design pattern used in Narratory - a dialog is built up by a collection of turns, with each Turn being either a Bot turn (when the bot speaks) or a User turn (when the user speaks).

In addition, there are three parts of the dialog separated by empty lines. These sections are called Bot initiatives since the Bot starts each of these parts of the dialog. Each of these bot initiatives can be seen as their own subdialogs, but they are always executed in sequence.

We call this sequence of these Bot initiatives the Narrative of the application. The Narrative is typically the main path through the interaction.

A narrative could, for example, consist of the following Bot initiative BotTurns for a bot that help schedule deliveries:

  1. Greeting the user
  2. Asking if the user wants to make a delivery
  3. Asking the user the size and weight of the package
  4. Asking where the user wants to send the item
  5. Asking the user to confirm the delivery order
  6. Saying goodbye

Each of these BotTurns can have any number of back-and-forth turns between the bot and the User. After each turn in the narrative is completed, the bot will continue with the next Bot initiative BotTurn in the narrative unless the designer instructs it to do otherwise (for example jump to another part of the dialog).

User initiatives

What if users have their own agenda, perhaps asking questions? For example, they might ask what delivery costs in the above example.

In this case, a likely behavior that you want to answer the question (and any potential followup questions the user might have) but then return to the narrative where you were. This is a key concept in Narratory, that in addition to the narrative you also have User initiatives - similar sub dialogs like Bot initiatives but initiated by user turns.

To visualize this, an actual script with a user (split into the above snippets) might then turn out like this:

Bot: Hi there!
User: Hi
Bot: Do you want to make a delivery?
User: Where do you deliver to? // <-- User initiative (deviation from narrative)
Bot: For now, to any address in the Stockholm municipality // <-- Answer to question
Bot: So, do you want to make a delivery?
User: Yes
Bot: Awesome.
Bot: How big and heavy is the package?
User: It's small and weighs maybe two kilos
Bot: Okay.
Bot: And where do you want it delivered?
User: To my office
Bot: I got an address here for Industrigatan 4c, is that correct?
User: Yes
Bot: Ok.
Bot: That is all I need for now, should I book it for you?
User: How much does it cost? // <-- Deviation from narrative
Bot: For a two-kilo, small package it costs 5 USD. // <-- Answer to question
Bot: Now, should I book it for you? // <-- Return to the narrative
User: Yes
Bot: Great, confirming order.
Bot: You have a confirmation in your email shortly. Thanks for this! Bye!

Above, answers to the two questions posed by the user ("Where do you deliver to?" and "How much does it cost"?) could be implemented as User initiatives UserTurns, meaning that the user can ask these questions at any point in the dialog. It is also possible to include followup questions or to branch off the dialog using these user initiatives.

Note that each user initiative can lead to a complete sub dialog in itself with a deep structure of bot and user turns. It is also possible to jump to another part in the narrative. In addition, a snippet in the narrative can have conditions set, which could for example ensure that the snippet only should be entered if the user is a returning user, or if an order has been made.


This showcases the basic building blocks of Narratory; Bot turns and User turns making up sub dialogs called Bot initiatives (a sequence of these are called the Narrative) and User initiatives.