Skip to main content

Introduction

This document walks through the background and purpose of Narratory.

What and why Narratory is#

Narratory is a platform-independent service for building engaging and scalable chat-bots and voice-apps. Based on research in dialog systems, Narratory (unlike most if not all other creation tools for conversational apps) takes a dialog and script-first approach based on the notion that the best way to model conversations is through dialog scripts. 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, 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.

Since dialogs are largely text, text editors are actually the most intuitive interface to design dialog. Now, you probably are thinking something along these lines:

"But hey, the above snippet is far from realistic. The actors are just following a script, there's no variation. Each actor knows exactly what the other one will say at any point"

This is an excellent point. One of the beautiful, and similarly most challenging, parts of designing dialogs for voice or chat applications is that users can answer in a multitude of ways. Typically, however, you can narrow down the users' likely responses to a (hopefully manageable) set of intents. Wouldn't then a flow-diagram, with system utterances as nodes and user responses as connectors, be a better way to represent the dialog? Well, it turns out that it is actually quite manageable to use a slightly more syntactic version of the above if you want to allow branching of the user responses:

Bot: Hello there, 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 BotTurn (when the bot speaks) or a UserTurn (when the user speaks).

In addition, the observant user might note that above, there are two parts of the dialog separated by an empty line. These two sections are called Bot initiatives since the Bot starts each of these parts of the dialog. We call the 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).

Now, you might think:

But 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 of 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 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 narrative    Bot: For a two-kilo, small package it costs 5 USD. // <-- Answer to questionBot: Now, should I book it for you? // <-- Return to the narrativeUser: 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 narrative - see jumping in narrative. In addition, a snippet in the narrative can have conditions set, which could, for example, say that the snippet only should be entered if the user is a returning user, or if an order has been made. More on this in conditionals in narrative.

This showcases the basic building blocks of Narratory; Bot turns and User turns making dialog snippets that are either part of Bot initiatives or User initiatives, and finally a narrative composed of BotTurn initiatives and a bank of User initiative UserTurns.

With that said, it's about time we start looking at how the actual Narratory dialog scripts look like. Jump over to learn about the Basic building blocks.