Interaction Machine

class ConfigReadEvent()

IMEvent() fired immediately after sandbox configuration is read.

Arguments:
  • im (InteractionMachine) – the interaction machine firing the event.
  • config (object) – the config object.

The event type is config_read.

class IMEvent()

An event fired by the interaction machine.

Arguments:
  • ev (string) – the event type.
  • im (InteractionMachine) – the interaction machine firing the event.
  • data (object) – additional event data.
class InboundEventEvent()

IMEvent() fired when an message status event is received. Typically this is either an acknowledgement or a delivery report for an outbound message that was sent from the sandbox application.

Arguments:
  • im (InteractionMachine) – the interaction machine firing the event.
  • event (object) – the event message received.

The event type is inbound_event.

class InteractionMachine()
Arguments:
  • api (SandboxAPI) – a sandbox API providing access to external resources and inbound messages.
  • state_creator (StateCreator) – a collection of states defining an application.

A controller that handles inbound messages and fires events and handles state transitions in response to those messages. In addition it serves as a bridge between a StateCreator() (i.e. set of states defining an application) and resources provided by the sandbox API.

static api

A reference to the sandbox API.

static api_request(cmd_name, cmd)

Raw request to the sandbox API.

Arguments:
  • cmd_name (string) – name of the API request to make.
  • cmd (object) – API request data.

Returns a promise that fires with the response to the API request.

static attach()

Register the interaction machine’s on_unknown_command, on_inbound_message and on_inbound_event with the sandbox API and set the interaction machine itself as api.im.

static config

The value of the config key retrieved from the sandbox config resource. Available once InteractionMachine.setup_config() has been called by InteractionMachine.on_inbound_message().

static current_state

The current State() object. Updated whenever a new state is entered via a called to InteractionMachine.switch_state().

static done()

Terminate this sandbox instance.

static event(event)

Fire an event from the interaction machine to its state creator.

Arguments:
  • event (IMEvent) – the event to fire.
static fetch_config_value(key, json, done)

Retrieve a value from the sandbox application’s Vumi Go config.

Arguments:
  • key (string) – name of the configuration item to retrieve.
  • json (boolean) – whether to parse the returned value using JSON.parse. Defaults to false.
  • done (function) – function f(value) to call once the value has been returned by the config resource.
static fetch_translation(lang, done)

Retrieve a jed instance containing translations for the given language.

Arguments:
  • lang (string) – two letter language code (e.g. sw, en).
  • done (function) – function f(jed) to call with the jed instance containing the translations.

Translations are retrieve from the sandbox configuration resource by looking up keys named translation.<language-code>.

static get_msg()

Returns the inbound user msg object currently being processed by the interaction machine. Returns null if no message is being processed.

static get_user_answer(state_name)

Return the answer stored for a particular state.

Arguments:
  • state_name (string) – name of the state to retrieve the answer for.

Returns the value stored or null if no value is found.

static i18n

A jed gettext object for the current user. Updated whenever a new state is entered via a called to InteractionMachine.switch_state().

static i18n_lang

Two-letter language code for the user’s language. Updated whenever a new state is entered via a called to InteractionMachine.switch_state().

static load_user(from_addr)

Load a user’s current state from the key-value data store resource.

Arguments:
  • from_addr (string) – The address (e.g. MSISN) of the user.

Returns a promise that fires once the user data has been loaded.

static log(message)

Log a message to the sandbox logging resource at the info level.

Arguments:
  • message (string) – the log message.

Returns a promise that fires once the log message as been acknowledged by the logging resource.

static metrics

A default MetricStore() instance. Available once InteractionMachine.setup_metrics() has been called by InteractionMachine.on_inbound_message().

static msg

The message command currently being processed. Available as soon as InteractionMachine.on_inbound_message() is called.

static on_inbound_event(cmd)

Handle a message event (e.g. an acknowledgement or delivery report).

Arguments:
  • cmd (object) – The API request cmd containing the message event.

Fires an InboundEventEvent() containing the event.

This method terminates the sandbox once the event has been processed.

static on_inbound_message(cmd)

Handle an inbound user message triggering state transitions and events as necessary.

Arguments:
  • cmd (object) – The API request cmd containing the inbound user message.

The steps performed by this method are roughly:

Afterwards this method terminates the sandbox.

static on_unknown_command(cmd)

Called by the sandbox API when a command without a handler is received. Logs an error and terminates the sandbox instance.

Arguments:
  • cmd (object) – The API request that no command handler was found for.

The handlers currently implemented are:

static refresh_i18n()

Re-fetches the appropriate language translations if the user’s language setting has changed since translations were last loaded. Sets self.i18n to a new jed instance and sets self.i18n_lang to self.user.lang.

Returns a promise that fires once the translations have been refreshed.

static reply(msg, save_user)

Send a response from the current state to the user.

Arguments:
  • msg (object) – the inbound message being replied to.
  • save_user (boolean) – whether to save the user state.

Returns a promise which fires once the response has been sent and the user state successfully stored.

static set_user_answer(state_name, answer)

Sets the answer for the given state.

Arguments:
  • state_name (string) – name of the state the answer is for.
  • value (object) – value of the answer (usually a string).

This is called by State() objects when they determine that the user has submitted an answer.

static set_user_lang(lang)
Arguments:
  • lang (string) – The two-letter code of the language the user has selected. E.g. en, sw.
static set_user_state(state_name)

Sets the stored value of the user’s current state.

Arguments:
  • state_name (string) – name of the state the user is now in.

This only sets the stored value of the user’s state. Actual state changes are handled by switch_state() which calls this method.

static setup_config()

Retrieves the sandbox config and stores it on the interaction machine as self.config for later use. Fires a ConfigReadEvent() so that state creators may perform application specific setup.

static setup_metrics()

Assign a MetricStore() instance to self.metrics. The store name is read from self.config.metric_store (with the name default as the default).

static state_creator

A reference to the StateCreator().

static store_user(from_addr, user)

Save a user’s current state to the key-value data store resource.

Arguments:
  • from_addr (string) – The address (e.g. MSISN) of the user.
  • user (object) – The user state to save.

Returns a promise that fires once the user data has been saved.

static switch_state(state_name)

Switch to a new state.

Arguments:
  • state_name (string) – Name of the state to switch to.

This method returns a promise that fires once the state transition is complete.

If the current state has the same name as state_name, no state transition occurs. Fires StateExitEvent() and StateEnterEvent() events as appropriate.

static user

User data for the current user. Available once InteractionMachine.load_user() has been called by InteractionMachine.on_inbound_message().

static user_addr

Address of current user (e.g. their MSISDN). Available once InteractionMachine.load_user() has been called by InteractionMachine.on_inbound_message().

static user_key(from_addr)

Return the key under which to store user state for the given from_addr.

Arguments:
  • from_addr (string) – The address (e.g. MSISDN) of the user.

User state may be namespaced by setting config.user_store to a prefix to store the application’s users under.

class NewUserEvent()

IMEvent() fired when a message arrives from a user for whom there is no user state (i.e. a new unique user).

Arguments:

The event type is new_user.

class SessionCloseEvent()

IMEvent() fired when a user session ends.

Arguments:
  • im (InteractionMachine) – the interaction machine firing the event.
  • boolean (possible_timeout) – true if the session was terminated by the user (including when the user session times out) and false if the session was closed explicitly by the sandbox application.

The event type is session_close.

class SessionNewEvent()

IMEvent() fired when a new user session starts.

Arguments:

The event type is session_new.

class SessionResumeEvent()

IMEvent() fired when a new user message arrives for an existing user session.

Arguments:

The event type is session_resume.

State.start_state_creator(state_name, im)
Arguments:
  • state_name (string) – the name of the start state.
  • im (InteractionMachine) – the interaction machine the start state is for.

This default implemenation looks up a creator for the state named state_name and calls that. If no such creator exists, it calls error_state_creator instead.

class StateCreator()
Arguments:
  • start_state (string) – Name of the initial state. New users will enter this state when they first interact with the sandbox application.

A set of states defining a sandbox application. States may be either statically created via add_state, dynamically loaded via add_creator or completely dynamically defined by overriding switch_state.

static add_creator(state_name, state_creation_function)
Arguments:
  • state_name (string) – name of the state
  • state_creation_function (function) – A function func(state_name, im) for creating the state. This function should take the state name and interaction machine as parameters and should return a state object either directly or via a promise.
static add_state(state, translate)
Arguments:
  • state (State) – the state to add.
  • translate (boolean) – whether the state should be re-translated each time it is accessed. The default is true.
static error_state_creator(state_name, im)
Arguments:
  • state_name (string) – the name of the state for which an error occurred.
  • im (InteractionMachine) – the interaction machine in which the error occurred.

This default implementation creates an EndState with name state_name and content “An error occurred. Please try again later”.

The end state created has the next state set to null so that:

  • It won’t set the next state.
  • When switch_state() is next reached, we identify that the user currently has no state, and use the start state instead.

If the start state still does not exist, another error state will be created.

static on_event(event)
Arguments:
  • event (IMEvent) – the event being fired.

Called by the interaction machine when an IMEvent() is fired. This method dispatches events to handler methods named on_<event_type> if such a handler exist.

Handlers should accept a single parameter, namely the event being fired.

Handler methods may return promises.

static switch_state(state_name, im)
Arguments:
  • state_name (string) – the name of the state to switch to.
  • im (InteractionMachine) – the interaction machine the state is for.

Looks up a creator for the given state_name and calls it. If the state name is undefined, calls start_state_creator instead.

This function returns a promise.

It may be overridden by StateCreator() subclasses that wish to provide a completely dynamic set of states.

class StateEnterEvent()

IMEvent() fired when a user enters a state from a different state.

Arguments:
  • im (InteractionMachine) – the interaction machine firing the event.
  • state (object) – the state object being entered.

The event type is state_enter.

class StateExitEvent()

IMEvent() fired when a user exits a state to a different state.

Arguments:
  • im (InteractionMachine) – the interaction machine firing the event.
  • state (object) – the state being left.
  • user (object) – the user leaving the state.

The event type is state_exit.