Interaction Machine

class ApiError(message)

Thrown when an error occurs when the sandbox api returns a failure response (when success is false).

Arguments:
  • reply (object) – the failure reply given by the api.
class IMErrorEvent(im)

Emitted when an error occurs during a run of the im.

Arguments:

The event type is im:error.

class IMEvent()

An event relating to an interaction machine.

Arguments:
  • name (string) – the event type’s name.
  • im (InteractionMachine) – the interaction machine associated to the event
class IMShutdownEvent(im)

Occurs when the im is about to shutdown.

Arguments:

The event type is im:shutdown.

class InboundEventEvent(im, cmd)

Emitted 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 emitting the event.
  • cmd (object) – the API request cmd containing the inbound user message.

The event type is inbound_event.

class InboundMessageEvent(im, cmd)

Emitted when an inbound user message is received by the interaction machine.

Arguments:
  • im (InteractionMachine) – the interaction machine firing the event.
  • cmd (object) – the API request cmd containing the inbound user message.
class InteractionMachine(api, app)
Arguments:
  • api (SandboxAPI) – a sandbox API providing access to external resources and inbound messages.
  • app (App) – 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 App() (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 fulfilled with the response to the API request, or rejected with a ApiError() if a failure response was given.

static app

A reference to the App().

static attach()

Attaches the im to the given api and app. The sandbox API’s event handlers are set to emit the respective events on the interaction machine, then terminate the sandbox once their listeners are done.

static config

A IMConfig() instance for the IM’s config data. Available when setup is complete (see InteractionMachine.setup()).

static contacts

A default ContactStore() instance for managing contacts. Available when setup is complete (see InteractionMachine.setup())

static create_and_set_state(state)

Creates new state using the given StateData() or state name, then sets it as the InteractionMachine()‘s current state.

Arguments:
  • state (object, string, or StateData) – The state to create and set
static create_state(state)

Creates a new state using the given StateData() or state name.

Arguments:
  • state (object, string, or StateData) – The state to create
static done()

Saves the user, then terminates the sandbox instance.

static enter_state(state)

Creates the given state, sets it as the current state, then emits a :class:StateEnterEvent` (on :class:InteractionMachine, then the new state).

Arguments:
  • state (object, string, or StateData) – the state to enter
static exit_state()

Emits a :class:StateExitEvent` (on :class:InteractionMachine, then the state), then resets the interaction machine’s state to null. If the interaction machine is not on a state, this method is a no-op.

static fetch_translation(lang)

Retrieve a Translator() instance corresponding to the translations for the given language. Returns a promise that will be fulfilled with the retrieved translator.

Arguments:
  • lang (string) – two letter language code (e.g. sw, en).

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

static groups

A default GroupStore() instance for managing groups. Available when setup is complete (see InteractionMachine.setup())

static handle_message(msg)

Delegates to its subordinate message handlers to handle an inbound message based on the message’s session event type. The fallback message handler is defined by InteractionMachine.handle_message.fallback(), which by default is an alias for InteractionMachine.handle_message.resume().

If the user is not currently in a session (which happens for new users and users that have reached an EndState() in a previous session), and the message does not have a session_event (as is the case for session-less messages such as smses or tweets), we assume the user is starting a new session.

Arguments:
  • msg (object) – the received inbound message. *
static log

A Logger() instance for logging message in the sandbox.

static metrics

A default MetricStore() instance for emitting metrics. Available when setup is complete (see InteractionMachine.setup())

static msg

The message command currently being processed. Available when setup is complete (see InteractionMachine.setup()).

static next_state

The next state that the user should move to once the user’s input has been processed.

static on "inbound_message"(event)

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

Arguments:
The steps performed by this method are roughly:
static on "unknown_command"(event)

Invoked by a UnknownCommandEvent() event when a command without a handler is received (see UnknownCommandEvent()). Logs an error.

Arguments:
static outbound

A OutboundHelper() for sending out messages. Available when setup is complete (see InteractionMachine.setup())

static reply(msg)

Send a response from the current state to the user.

Returns a promise which is fulfilled once the response has been sent.

static resume(state)

Creates the given state, sets it as the current state, then emits a :class:StateResumeEvent` (on :class:InteractionMachine, then the new state).

If the created state has a different name to the requested state, a StateEnterEvent() is emitted instead. This happens, for example, if the requested state does not exist (see AppStates.create()).

Arguments:
  • state (object, string, or StateData) – the state to resume
static sandbox_config

A SandboxConfig() instance for accessing the sandbox’s config data. Available when setup is complete (see InteractionMachine.setup()).

static set_state(state)

Sets the given State() as the InteractionMachine()‘s current state.

Arguments:
  • state (State) – The state set as the current state
static setup(msg[, opts])

Sets up the interaction machine using the given message.

Arguments:
  • msg (object) – the received message to be used to set up the interaction machine.
  • opts.reset (boolean) – whether to reset the user’s data, or load them from the kv store
The IM sets up its attributes in the following order:
  • sanbox config
  • im config
  • metric store
  • user
  • app

Finally, the user’s creation_event is emitted, then a SetupEvent() is emitted for the interaction machine. A promise is returned, which will be fulfilled once all event listeners are done.

static state

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

static switch_state(dest)

Switches the IM from its current state to the given destination state. Returns a promise fulfilled once the switch has completed.

Arguments:
  • dest (object, string, or StateData) – the destination state’s name or state data
The following steps are taken:
static user

A User() instance for the current user. Available when setup is complete (see InteractionMachine.setup()).

InteractionMachine.handle_message.close(msg)

Invoked when an inbound message is received with a close session event type. Emits a SessionCloseEvent() on the interaction machine and waits for its listeners to complete their work.

Arguments:
  • msg (object) – the received inbound message.
InteractionMachine.handle_message.new(msg)

Invoked when an inbound message is received with a new session event type.

Arguments:
  • msg (object) – the received inbound message.

Does roughly the following:

  • Emits a SessionNewEvent() on the interaction machine and waits for its listeners to complete their work
  • Sends a reply from the current state.
InteractionMachine.handle_message.resume(msg)

Invoked when an inbound message is received with a resume session event type.

Arguments:
  • msg (object) – the received inbound message.

Does roughly the following:

  • Emits a SessionResumeEvent() on the interaction machine and waits for its listeners to complete their work
  • If the message contains usable content, give the content to the state (which fires a StateInputEvent()).
  • Send a reply from the current state.
class ReplyEvent(im)

Emitted after the interaction machine sends a reply to a message sent in by the user.

Arguments:
  • im (InteractionMachine) – the interaction machine emitting the event.
  • content (string) – the content of the reply
  • continue_session (bool) – true if the reply did not end the session, false if the reply ended the session.

The event type is reply.

class SessionCloseEvent(im, user_terminated)

Emitted when a user session ends.

Arguments:
  • im (InteractionMachine) – the interaction machine emitting the event.
  • user_terminated (boolean) – 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(im)

Emitted when a new user session starts.

Arguments:

The event type is session:new.

class SessionResumeEvent(im)

Emitted when a new user message arrives for an existing user session.

Arguments:

The event type is session:resume.

class UnknownCommandEvent(im, cmd)

Emitted when a command without a handler is received.

Arguments:
  • im (InteractionMachine) – the interaction machine emitting the event.
  • cmd (object) – the API request that no command handler was found for.

The event type is unknown_command.

interact(api, f)

If api is defined, create an InteractionMachine() with the App() returned by f. Otherwise do nothing.

If f is an App() subclass, new f() is used to construct the application instance instead.

Arguments:
  • api (SandboxAPI) – a sandbox API providing access to external resources and inbound messages
  • f (function) – a function that returns an App() instance or an App() class.

Returns the InteractionMachine() created or null if no InteractionMachine() was created.

Usually the return value is ignored since creating an InteractionMachine() attachs it to the api.