Flow

A flow consists of following definitions:

• intents : Dict<Intent> - Intent definitions
• states : Dict<State> - State definitions
• actions : Dict<Action> - Action definitions
• methods : Dict<string> - Flow-specific method definitions

Additionally a flow can be set as following:

• active : boolean
  You can enable/disable a flow by setting the active field of a flow
• volatile : boolean
  Set to true will close the flow whenever it goes outside the flow
• expire : number
  Will set flow to expire after specified number of miliseconds

Intents

Intent can be defined as following:

intents:
  <name>: <Intent>

The intent description contains following fields:

• type : "text" | "command" | "data"
  Type filter to define type of the message to be associated with this intent
• condition : string | string[]
  Condition filter to rule out certain intents to be selected
• classifier : Classifier | Classifier[]
  Classifier definition
• attributes : Dict<Attribute>
  Attributes / slotfilling associated with the intent
• fallback : boolean
  Define intent as fallback intent.
• priority : number
  Set priority of an intent for the selection process
• initial : boolean
  Set whether intent can be triggered only in current flow or from other flow as well

Condition

Condition is every valid javascript expression returning a boolean. Avaliable variables are:

• type : string - Message Type
• payload : JsonObject - Message Payload
• content : string - Message Content
• context : JsonObject - Flow Context
• data : JsonObject - Session Data
• config : JsonObject - Bot Config

Example:

condition: type == 'text' && content == 'hello' && !context.completed

Classifier

Classifier consists of following fields:

• nlu : string - Name of defined NLU or NLU-type
• hint : string - Prepend message with a text fragment
• match : string - Match result of the classifier with a specific string
• options : JsonObject - Override NLU options
• process : method | method[] - Postprocess intent using methods

Example:

classifier:
  nlu: topicClassifier
  match: food
  options:
    lowerCase: true
    threshold: 0.8

Example Multiple Classifiers:

classifier:
  - nlu: topicClassifier
    match: food
  - nlu: keywordClassifier
    match: food

Example mapping label using dict:

classifier:
    nlu: topicClassifier
    match: food
    dict:
        food: [food_a, food_b], # group multiple classes to one
        test: testing # change label

Attributes

Attribute consist of following fields:

• nlu : string - Name of defined NLU or NLU-type
• hint : string - Prepend message with a text fragment
• path : string - Result path to be taken
• options : JsonObject - Override NLU options
• process : method | method[] - Postprocess intent using methods

Example:

attributes:
  city:
    nlu: genericNER
    path: LOCATION
    options:
      threshold: 0.6
    process:
      - filterCity
      - capitalize

Example normalizing using dict:

attributes:
  city:
    nlu: genericNER
    path: location
    options:
      threshold: 0.6
    dict:
      jakarta: [jkt, jekardah, jakarta]
      bandung: [bdg, bandung]
      default: invalid

States

States can be defined as following:

states:
  <name>: <State>

The state description contains following fields:

• initial : boolean
  Specify initial state
• action : string | StateAction | StateAction[]
  Specify action to be executed
• end : boolean
  Specify end state
• transitions : Dict<Transition|string>
  Specify transitions
• float : Transition
  Specify floating transition
• enter : Mapping | method
  Specify mapping or method to be executed when state is entered
• transit : Mapping | method
  Specify mapping or method to be executed when transition is started
• exit : Mapping | method
  Specify mapping or method to be executed when state is exited

Mapping

Mapping is a procedure to update context / data. available variables are:

• attributes : JsonObject
  attributes that is captured by intent
• intent : string
  captured intent
• content : string
  message content
• payload : JsonObject
  message payload
• context : JsonObject
  Flow context
• data : JsonObject
  Session data

Example:

enter:
  data.name: attributes.name
  context.count: (context.count || 0)++

Example using method:

enter: someMapping

method definition:

methods:
  someMapping(ctx): > # {intent, attributes, content, payload, data, context}
    ctx.data.name = ctx.attributes.name;
    ctx.context.count++;
    return ctx;

State Actions

Action can be defined as a single action or multiple actions. The state action definition contains following fields:

• name : string - name of defined action or action type
• condition : string - condition filter
• options : JsonObject - override action options

Example:

action:
  name: reply
  options:
    text: 'hi!'

Example multiple actions:

action:
  - name: reply
    condition: context.mood = 'good'
    options:
      text: 'hi $(data.name)!'
  - name: reply
    condition: context.mood = 'bad'
    options:
      text: 'apaan sih kamu!'

You can simplify state actions (if you only have 1 action in some states) :

action: someAction

Transition

Transition define condition that leads to moving from one state to the other state. A transition is defined as following:

transitions:
  <destination>: <Transition>

Field definition:

• condition : string - Condition that trigger the transition
• priority : number - Priority for transition selection
• fallback : boolean - Define fallback when no other transition matches
• mapping : Mapping | method - Define mapping or method that is triggered during this transition

Example:

transitions:
  askDob:
    condition: "intent == 'yes' && !context.personGender && context.verifyGender"
    mapping:
      context.personGender: 'context.verifyGender'
      context.verifyGender: 'null'

You can simplify transitions definition :

transitions
    askDob: "intent == 'yes' && !context.personGender"

Floating State

Normally it is tedious if we have to define a transition to a state that is available in every state. e.g. Cancel state. To mitigate this we can define a floating transition. The system will automatically attach this transition in every state.

float: <Transition>

Events

We can define a mapping or method that is triggered during these events:

• enter - this event is triggered when entering a state
• transit - this event is triggered before transition process
• exit - this event is triggered after transition process

Meta Context

Additional meta context accessible in states at context.<meta>:

• $start : boolean - true if state is initial state
• $to : string - describe destination state. Available during exit
• $from : string - describe origin state. Available during enter
• $end : boolean - true if state is end state

Example:

states:
  stateA:
    enter:
      context.stateACount: (context.stateACount || 0)++
    transit:
      context.name: attributes.name || null
    exit:
      context.stateA.to: context.$to

Actions

Actions can be defined as following:

actions:
  <name>: <Action>

Following fields are available:

• type : string - action type.
• method : method - specify if action type is method
• options: JsonObject - action options
• condition : string - action condition

Example:

actions:
  askName:
    type: reply
    options:
      text: 'nama kamu siapa?'

Available action types are described in Action Types.

Flow Switching

Whenever bot reaches a state that is not an end state, the flow will stay open. The following message will trigger a transition to the next state. There is a case where the incoming message cannot be handled by any intents in current flow. In that case it will try to find a flow with a matching intent. When the second flow closes, the system will create internal message reenter.

{
    type: "command",
    content: "reenter",
    payload: null
}

this reenter need to be catched by the previous flow that is open:

intents:
  reenter:
    type: command
    condition: content == "reenter"