Introduction

During a conversation there is often a need to store some values somewhere and use them again on a later stage. This could be for example keeping the name of your user and then using it later to personalize messages like Thanks, {name}!. Or you might want to ask your users a sequence of questions and then push them to your database.

For this cases and others we use State. The State object is part of the Flow and allows you to store and manage key-value information as you go, and reuse it later in messages or functions.

Following this document will give you a brief overview about how to set and read data from State objects.

Store Data

Any data is stored in the State object as a key-value form.

By default, Nodes output are stored automatically in the State with under the generated key node.identifeier . For example, consider the following prompt node:

get_username:
  type: prompt
  prompt_type: text
  messages:
    - "Hi, what is your name please?"

One this node execution is completed (aka the user has given a valid input), the output object of this Node will be stored in the State under the key state.get_username.text with the value presenting the username.

Set command

You may use the set command to store custom values in the State. set command can be invoked when routing between Nodes in the same Flow:

get_username:
  type: prompt
  prompt_type: text
  messages:
    - "Hi, what is your name please?"
  on_complete:
    set:
      name: "{output.text}"

Manage lists in State

Use append operator to add store multiple items as a list in the State:

add_to_list:
  type: prompt
  prompt_type: text
  messages:
    - "Which book would you like to add to your reading list?"
  on_complete:
    set:
      append:
      - state.books: "{output.text}"

Read Data

Messages

Use the binding operator {state.key} to bind variables from the state to messages you send, for example, consider the following node greeting_node

greeting_node:
  type: notify
  messages:
    - "Hi, {state.name}. It's so nice to have you here!"
  on_complete: handoff

In this case we bind the value under the key username from the State to the message text.

Bind Params

State values can be also bound to the params object, which is used when across Nodes as for instance when invoking a function:

create_new_user:
  type: func
  func_id: myapp.create_user
  params:
    user_name: "{state.username}"

In the above example, then function create_user will be invoked with the parameter user_name and the value will be as

Functions

When invoking a function inside a Flow, a snapshot of the State object is passed to the invoked function. You can then manipulate the data and operate on it as you need.

def do_something(event, user, state, params):
    user_name = state['username']
    print(user_name)

function doSomething(event, user, state, params) {
    const userName = state.username
    console.log(userName)
}