User

User() is used for short-term information about a user interacting with your application. Most of this information relates to the current interaction session with the user, and includes the user’s current state, user’s answers to previous states and language preference. While User() is used for short-term information about a user, a Contact() holds long-term information.

User(im)

A structure for managing the current user being interacted with in InteractionMachine().

Arguments:
static create(addr, opts)

Invoked to create a new user. Simply delegates to User.setup(), but sets the user’s creation_event to UserNewEvent(). Intended to be used to explicitly differentiate newly created users from loaded users with a single action.

static created

Whether this is a new or loaded user.

static default_ttl()

Returns the default expiry time of saved user state (in seconds).

This may be set using the user_ttl sandbox config key. It defaults to 604800 seconds (seven days). Expiry may be disabled by setting user_ttl to null.

static fetch()

Fetches the user’s current state data from the key-value data store resource. Returns a promised fulfilled with the fetched data.

static get_answer(state_name)

Get the user’s answer for the state associated with state_name.

Arguments:
  • state_name (string) – the name of the state to retrieve an answer for
static is_in_state([state_name])

Determines whether the user is in the state represented by state_name, or whether the user is in any state at all if no arguments are given.

Arguments:
  • state_name (string) – the name of the state compare with
static key()

Returns the key under which to store user state. If user.store_name is set, stores the user under users.<store_name>.<addr>, or otherwise under users.<addr>.

static load(addr[, opts])

Load a user’s current state from the key-value data store resource, then sets the user’s creation_event to UserLoadEvent(). Throws an error if loading fails.

Returns a promise that is fulfilled when the loading and event emitting has completed.

Accepts the same params as User.setup(), where the opts param contains overrides for the loaded user data.

static load_or_create(addr[, opts])

Attempts to load a user’s current state from the key-value data store resource, creating the user if no existing user was found. Sets the user’s creation_event to UserLoadEvent() if the user was loaded, and UserNewEvent() if the user was created.

Returns a promise that is fulfilled when the loading and event emitting has completed.

Accepts the same params as User.setup(), where the opts param contains overrides for the loaded user data.

static make_key(addr[, store_name])

Makes the key under which to store a user’s state. If store_name is set, stores the user under 'users.<store_name>.<addr>, or otherwise under <addr>.

Arguments:
  • addr (string) – The address used as a key to load and save the user.
  • store_name (string) – The namespace path to be used when storing the user.
static refresh_i18n()

Re-fetches the appropriate language translations. Sets user.i8n to a new Translator() instance.

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

static reset(addr, opts)

Invoked to create a new user. Simply delegates to User.setup(), but sets the user’s creation_event to a UserResetEvent(). Intended to be used to explicitly differentiate reset users from both newly created users and loaded users with a single action.

static save()

Save a user’s current state to the key-value data store resource, then emits a UserSaveEvent().

Arguments:
  • opts.seconds (object) – How long the user’s state should be stored for before expiring. See User.default_ttl() for how the default is determined.

Returns a promise that is fulfilled once the user data has been saved and events have been emitted.

static serialize()

Returns an object representing the user. Suitable for JSON stringifying and storage purposes.

static set_answer(state_name, answer)

Sets the user’s answer to the state associated with state_name.

Arguments:
  • state_name (string) – the name of the state to save an answer for
  • answer (string) – the user’s answer to the state
static set_lang(lang)

Gives the user a new language. If the user’s language has changed, their translator is is refreshed (delegates to User.refresh_i18n()). Returns a promise that will be fulfilled once the method’s work is complete.

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

Sets up the user. Returns a promise that is fulfilled once the setup is complete.

Performs the following steps:
  • Processes the given setup arguments
  • Attempts to refresh the translator (involves interaction with the sandbox api).
  • Emits a SetupEvent()
Arguments:
  • addr (string) – the address used as a key to load and save the user.
  • opts.lang (string) – the two-letter code of the language the user has selected. E.g. ‘en’, ‘sw’.
  • opts.store_name (string) – an additional namespace path to be used when storing the user. See User.key().
  • opts.state.name (string) – the name of the state most recently visited by the user. Optional.
  • opts.state.metadata (string) – metadata about the state most recently visited by the user. Optional.
  • opts.in_session (boolean) – whether the user is currently in a session. Defaults to false.
class UserEvent(user)

An event relating to a user.

Arguments:
  • name (string) – the event type’s name.
  • user (User) – the user associated to the event.
class UserLoadEvent(user)

Emitted when an existing user is loaded. This typically happens in InteractionMachine() when message arrives from a user for who has already interacted with the system.

Arguments:
  • user (User) – the user that was loaded.

The event type is user:load.

class UserNewEvent(user)

Emitted when a new user is created. This typically happens in InteractionMachine() when message arrives from a user for whom there is no user state (i.e. a new unique user).

Arguments:
  • user (User) – the user that was created.

The event type is user:new.

class UserNewEvent(user)

Emitted when a user’s data is reset. This typically happens in InteractionMachine() when message arrives from a user for whom with its content being ”!reset”, forcing the user to be reset.

Arguments:
  • user (User) – the user that was reset.

The event type is user:reset.

class UserSaveEvent(user)

Emitted when a user is saved. This typically happens in InteractionMachine() after an inbound message from the user has been processed as one of the last actions before terminating the sandbox.

Arguments:
  • user (User) – the user that was saved.

The event type is user:save.