State reference

A reference guide to all the states available in the toolkit.

class State(name, opts)

Base class for states in the interaction machine. States can be thought of as a single screen in a set of interactions with the user.

Arguments:
  • name (string) – name used to identify and refer to the state
  • opts.metadata (object) – data about the state relevant to the interaction machine’s current user. Optional.
  • opts.send_reply (boolean) – whether or not a reply should be sent to the user’s message. Default is true. May also be a function, which may return its result via a promise.
  • opts.continue_session (boolean) – whether or not this is the last state in a session. Default is true. May also be a function, which may return its result via a promise.
  • opts.helper_metadata (object) – additional helper metadata to set on the reply sent to the user. Primarily useful for setting voice metadata for messages destined to be sent as voice calls. Default is null. May also be a function, which may return its result via a promise.
  • opts.check (function) – a function func(input) for validating a user’s response, where input is the user’s input. If a string or LazyText() is returned, the text will be taken as the error response to send back to the user. If a StateInvalidError() is returned, its response property will be taken as the error response to send back to the user. Any other value returned will be taken as a non-error. The result may be returned via a promise. See State.validate().
  • opts.events (object) –

    Optional event name-listener mappings to bind. For example:

    {
        'state:invalid': function(e) {
            console.log(e);
        }
    }
    
static display()

The content to be displayed to the user. May return a promise.

static init()

Invoked just after setup has completed, and just before ‘setup’ event is fired to provide subclasses with a setup hook. May return a promise.

static input()

Accepts input, invokes State.translate.before_input(), then emits a StateInputEvent`() to allow input to be processed.

static invalidate(response)

Invalidates the user’s state, sending the given response to the user. Sets the state’s self.error object to an appropriate error and emits a StateInvalidEvent().

Arguments:
  • response (string or LazyText()) – the response to send back to the user
static invalidate(error)

Invalidates the user’s state using an error. Sets the state’s self.error object to an appropriate error and emits a :class:StateInvalidEvent``.

Arguments:
static save_response(response)

Called by sub-classes to store accepted user responses on the user object.

Arguments:
  • response (string) – value to store as an answer.
static setup(im)

Called before any other methods on the state are called to allow the state to set itself up.

Arguments:
static show()

Translates the state using State.translators.before_display(), then displays its text.

static translate(i18n)

Translate’s a state’s text using the given translator. May return a promise.

Arguments:
  • i18n (Translator) – the translation function to be used for translating the text.
State.emit.input(im)

Shortcut for emitting an input event for the state (since this is done quite often). See StateInputEvent().

State.translators.before_display(i18n)

Translate’s a state’s text using the given translator. Invoked before text is displayed to the user. By default, just delegates to State.translate(). May return a promise.

Arguments:
  • i18n (Translator) – the translation function to be used for translating the text.
State.translators.before_input(i18n)

Translate’s a state’s text using the given translator. Invoked before user input is processed. By default, just delegates to State.translate(). May return a promise.

Arguments:
  • i18n (Translator) – the translation function to be used for translating the text.
State:set_next_state(name)

Set the state that the user will visit after this state using the given state name.

Arguments:
  • name (string) – The name of the next state
State:set_next_state(fn[, arg1[, arg2[, ...]]])

Use a function to set the state that the user will visit this state.

Arguments:
  • fn (function) – a function that returns name of the next state or an options object with data about the next state. The value of this inside f will be the calling state instance. May also return its result via a promise.
  • arg1, arg2, ... (arguments) – arguments to pass to fn
class StateEnterEvent()

Emitted when the state is entered by a user.

This happens when the state is switched to from another state, or when the state is created if this is the start of a new session).

Arguments:
  • state (State) – the state being entered.

The event type is state:enter.

class StateEnterEvent()

Emitted when the state is exited by the user. This happens immediately before the interaction machine switches to a different state (see StateEnterEvent()).

Arguments:
  • state (State) – the state being exited.

The event type is state:exit.

class StateError(state, message)

Occurs when interacting or manipulating a state causes an error.

Arguments:
  • state (State) – the state that caused the error.
  • message (string) – the error message.
class StateEvent(name, state, data)

An event relating to a state.

Arguments:
  • name (string) – the event type’s name.
  • state (State) – the state associated to the event.
class StateEvent(name, state, error)

Emitted when a state becomes invalid.

Arguments:
  • state (State) – the state associated to the event.
  • error (StateInvalidError) – the validation error that occured.
class StateInputEvent(content)

Emitted when the user has given input to the state.

Arguments:
  • state (State) – the state that the input was given to.
  • content (string) – text from the user.

The event type is state:input.

class StateInvalidError(state, response[, opts])

Occurs when a state receives invalid input. Raised either by a failed validation check or by explicitly calling State.invalidate().

Arguments:
  • state (State) – the state that caused the error.
  • response (string or LazyText) – the response to send back to the user.
  • opts.reason (string) – the reason for the error.
  • opts.input (string) – the user input that caused the error, if relevant
static translate(i18n)

Translate the error response.

Arguments:
  • i18n (Translator) – the translation function to be used for translating the text.
class StateResumeEvent()

Emitted when the state is resumed.

When the user enters input, the new sandbox run is started, causing the state to be re-created (or resumed) to process the user’s input. This means that when this event is emitted, the state has already been entered (see StateEnterEvent()) and its content has been shown to the user in a previous sandbox run (provided the session didn’t timeout when the send was attempted).

Arguments:
  • state (State) – the state being resumed.

The event type is state:resume.

class StateShowEvent()

Emitted when a state’s is shown to a user, immediately after State.display() has completed.

Arguments:
  • state (State) – the state being shown.
  • content (string) – the content being shown.

The event type is state:show.

class Choice(value, label)

An individual choice that the user can select inside a ChoiceState().

Arguments:
  • value (string) – string used when storing, processing and looking up the choice.
  • label (string) – string displayed to the user.
class ChoiceState(name, opts)

A state which displays a list of numbered choices, then allows the user to respond by selecting one of the choices.

Arguments:
  • name (string) – name used to identify and refer to the state
  • opts.question (string or LazyText) – text to display to the user
  • opts.choices (Array of Choice() objects) – ordered list of choices to display
  • opts.error (string or LazyText) – error text to display to the user if bad user input was given. Optional.
  • opts.accept_labels (boolean) – whether choice labels are accepted as the user’s responses. For eg, if accept_labels is true, the state will accepts both “1” and “Red” as responses responses if the state’s first choice is “Red”. Defaults to false.
  • opts.send_reply (boolean) – whether or not a reply should be sent to the user’s message. Defaults to true.
  • opts.continue_session (boolean) – whether or not this is the last state in a session. Defaults to true.
  • opts.next (fn_or_str_or_obj) – state that the user should visit after this state. May either be the name of the next state, an options object representing the next state, or a function of the form f(choice) returning either, where choice is the Choice() chosen by the user. If next is null or not defined, the state machine will be left in the current state. See State.set_next_state().
  • opts.events (object) – Optional event name-listener mappings to bind.
static process_choice(choice)

Return true if the choice has been handled completely or false if the choice should be propagated to the next state handler.

This allows sub-classes to provide custom processing for special choices (e.g. forward and back options for navigating through long choice lists).

Arguments:
  • choice (Choice) – choice to be processed.
static shorten_choices(text, choices)

Hook for replacing choices with shorter ones if needed.

class LanguageChoice(opts)

A state for selecting a language.

Arguments:
  • name (string) – name used to identify and refer to the state
  • opts.next (fn_or_str) – state that the user should visit after this state. Functions should have the form f(choice) and return the name of the next state or a promise that returns the name. The value of this inside f will be the calling ChoiceState() instance.
  • opts.question (string or LazyText) – text to display to the user
  • opts.error (string or LazyText) – error text to display to the user if we reach this state in error. Optional.
  • opts.accept_labels (boolean) – whether choice labels are accepted as the user’s responses. For eg, if accept_labels is true, the state will accepts both “1” and “Red” as responses responses if the state’s first choice is “Red”. Defaults to false.
  • opts.send_reply (boolean) – whether or not a reply should be sent to the user’s message. Defaults to true.
  • opts.continue_session (boolean) – whether or not this is the last state in a session. Defaults to true.
  • opts.events (object) – Optional event name-listener mappings to bind.

It functions exactly like ChoiceState() except that it also stores the value of the selected choices as the user’s language (it is still available as an answer too).

Choice() instances passed to this state should have two-letter language codes as values, e.g.:

new LanguageChoice(
    "select_language",
    {
        next: "next_state",
        question: "What language would you like to use?",
        choices: [ new Choice("sw", "Swahili"), new Choice("en", "English") ]
    }
);

A ChoiceState() whose Choice() values are either state names or state options objects. See State.set_next_state() for a description of the options objects.

Supports the same parameters as ChoiceState() except that opts.next isn’t available.

class PaginatedChoiceState(name, opts)

A choice state for displaying long lists of choices by spanning the choices across multiple pages.

Arguments:
  • name (string) – name used to identify and refer to the state
  • opts.next (fn_or_str) – state that the user should visit after this state. Functions should have the form f(choice) and return the name of the next state or a promise that returns the name. The value of this inside f will be the calling ChoiceState() instance.
  • opts.question (string) – text to display to the user
  • opts.error (string or LazyText) – error text to display to the user if we reach this state in error. Optional.
  • opts.accept_labels (boolean) – whether choice labels are accepted as the user’s responses. For eg, if accept_labels is true, the state will accepts both “1” and “Red” as responses responses if the state’s first choice is “Red”. Defaults to false.
  • opts.send_reply (boolean) – whether or not a reply should be sent to the user’s message. Defaults to true.
  • opts.continue_session (boolean) – whether or not this is the last state in a session. Defaults to true.
  • opts.back (string) – the choice label to display to the user for going back a page. Default is “Back”.
  • opts.more (string) – the choice label to display to the user for going to the next page Default is “Next”.
  • opts.options_per_page (int) – maximum number of choices to display per page. Default is 8. If this option is explicitly given as null, PaginatedChoiceState() will automatically divide up the given choices to fit within the character limit given by the 'characters_per_page' option.
  • opts.characters_per_page (int) – maximum number of characters to display per page. Default is null (i.e. no maximum), or 160 if the 'characters_per_page' option is explicitly given as null.
  • opts.events (object) – Optional event name-listener mappings to bind.
class BookletState(name, opts)

A state for displaying paginated text.

Arguments:
  • name (string) – name of the state
  • opts.pages (integer) – total number of pages.
  • opts.page_text (function) – function func(n) returning the text of page n. Pages are numbered from 0 to (pages - 1). May return a promise.
  • opts.initial_page (integer) – page number to use when the state is entered. Optional, default is 0.
  • opts.buttons (object) – map of user inputs to amounts to increment the page number by. The special value ‘exit’ triggers moving to the next state. Optional, default is: {"1": -1, "2": +1, "0": "exit"},
  • opts.footer_text (string) – text to append to every page. Optional, default is: "1 for prev, 2 for next, 0 to end."
  • opts.send_reply (boolean) – whether or not a reply should be sent to the user’s message. Defaults to true.
  • opts.continue_session (boolean) – whether or not this is the last state in a session. Defaults to true.
  • opts.next (fn_or_str_or_obj) – state that the user should visit after this state. May either be the name of the next state, an options object representing the next state, or a function of the form f(content) returning either, where content is the input given by the user. If next is null or not defined, the state machine will be left in the current state. See State.set_next_state().
  • opts.events (object) – Optional event name-listener mappings to bind.
class PaginatedState(name, opts)

Add state type that divides up the given text into pages.

Arguments:
  • name (string) – name used to identify and refer to the state
  • opts.text (string or LazyText) – the content to display to the user.
  • opts.page

    The function to use to determine the text shown to the user.

    The function should return the text to be displayed to the user as a string and take the form fn(i, text, n), where i` is the user’s 0-indexed current page number,``text`` is the translated text, n is the maximum number of characters that can fit on the page (after taking into account the nagivation choices) and this is the PaginatedState() instance.

    When the function returns a falsy value, page i - 1 is taken as the last page to be displayed to the user. The function may also return a promise fulfilled with the value.

    If this option is not provided, the PaginatedState() will use a default function that will display the words that fit on the page based on the values of i and the given 'characters_per_page' option.

  • opts.send_reply (boolean) – whether or not a reply should be sent to the user’s message. Defaults to true.
  • opts.characters_per_page (int) – maximum number of characters to display per page (including the characters needed for the navigation choices). Default is 160. 'back', 'more' and 'exit' choices.
  • opts.back (string) – the label to display to the user for going back a page. Defaults to 'Back'.
  • opts.more (string) – the label to display to the user for going to the next page. Defaults to 'More'.
  • opts.exit (string) – the choice label to display to the user for going to the next state. Defaults to 'Exit'.
  • opts.continue_session (boolean) – whether or not this is the last state in a session. Defaults to true.
  • opts.next (function or string) – state that the user should visit after this state. May either be the name of the next state, an options object representing the next state, or a function of the form f(content) returning either, where content is the input given by the user when the user chooses to exit the PaginatedState(). If next is null or not defined, the state machine will be left in the current state. See State.set_next_state().
  • opts.events (object) – Optional event name-listener mappings to bind.
class EndState(name, opts)

A state which displays text and then ends the session.

Arguments:
  • name (string) – name used to identify and refer to the state
  • opts.text (string or LazyText) – text to display to the user
  • opts.next (fn_or_str_or_obj) – state that the user should visit after this state. May either be the name of the next state, an options object representing the next state, or a function of the form f(content) returning either, where content is the input given by the user. If next is null or not defined, the state machine will be left in the current state. See State.set_next_state().
  • opts.events (object) – Optional event name-listener mappings to bind.
class FreeText(name, opts)

A state which displays a text, then allows the user to respond with any text.

Arguments:
  • name (string) – name used to identify and refer to the state
  • opts.question (string or LazyText) – text to display to the user.
  • opts.send_reply (boolean) – whether or not a reply should be sent to the user’s message. Defaults to true.
  • opts.continue_session (boolean) – whether or not this is the last state in a session. Defaults to true.
  • opts.check (function) – a function func(content) for validating a user’s response, where content is the user’s input. If a string LazyText() is returned, the text will be taken as the error response to send back to the user. If a StateInvalidError() is returned, its response property will be taken as the error response to send back to the user. Any other value returned will be taken as a non-error. The result may be returned via a promise. See State.validate().
  • opts.next (fn_or_str_or_obj) – state that the user should visit after this state. May either be the name of the next state, an options object representing the next state, or a function of the form f(content) returning either, where content is the input given by the user. If next is null or not defined, the state machine will be left in the current state. See State.set_next_state().
  • opts.events (object) – Optional event name-listener mappings to bind.