Skip to main content

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 thereActor 1: how are you doing?Actor 2: Oh, it's been a long dayActor 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 a sequence of these Bot initiatives a Flow.

A Flow 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 flow is completed, the bot will continue with the next Bot initiative BotTurn in the flow 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 flow where you were. This is a key concept in Narratory, that in addition to the bot initiatives in the Flow you also have User initiatives - similar sub dialogs as Bot initiatives but instead 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 flow)    Bot: For now, to any address in the Stockholm municipality // <-- Answer to questionBot: So, do you want to make a delivery?User: YesBot: Awesome.
Bot: How big and heavy is the package?User: It's small and weighs maybe two kilosBot: Okay.
Bot: And where do you want it delivered?User: To my officeBot: I got an address here for Industrigatan 4c, is that correct?User: YesBot: Ok.
Bot: That is all I need for now, should I book it for you?    User: How much does it cost? // <-- Deviation from flow    Bot: For a two-kilo, small package it costs 5 USD. // <-- Answer to questionBot: Now, should I book it for you? // <-- Return to the flowUser: YesBot: 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 flow, or to another narrative alltogether. 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 flow) and User initiatives.