Interaction Machine¶
-
class
ApiError
(message)¶ Thrown when an error occurs when the sandbox api returns a failure response (when
success
isfalse
).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: - im (InteractionMachine) – the interaction machine emitting the event.
- error (InteractionMachine) – the error that occured.
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: - im (InteractionMachine) – the interaction machine emitting the event.
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
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 (seeInteractionMachine.setup()
).
-
static
contacts
¶ A default
ContactStore()
instance for managing contacts. Available when setup is complete (seeInteractionMachine.setup()
)
-
static
create_and_set_state
(state)¶ Creates new state using the given
StateData()
or state name, then sets it as theInteractionMachine()
‘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>
.- lang (string) – two letter language code (e.g.
-
static
groups
¶ A default
GroupStore()
instance for managing groups. Available when setup is complete (seeInteractionMachine.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 forInteractionMachine.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 asession_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
metrics
¶ A default
MetricStore()
instance for emitting metrics. Available when setup is complete (seeInteractionMachine.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: - event (InboundMessageEvent) – the fired event.
- The steps performed by this method are roughly:
- Set up the IM (see
InteractionMachine.setup()
) - If the user is currently in a state (from a previous IM run), switch to this state.
- Otherwise, this is a new user, so switch to the IM’s configured start state
- Handle the message based on its session event type (see
InteractionMachine.handle_message()
).
- Set up the IM (see
-
static
on "unknown_command"
(event)¶ Invoked by a
UnknownCommandEvent()
event when a command without a handler is received (seeUnknownCommandEvent()
). Logs an error.Arguments: - event (UnknownCommandEvent) – the fired event.
-
static
outbound
¶ A
OutboundHelper()
for sending out messages. Available when setup is complete (seeInteractionMachine.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 (seeAppStates.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 (seeInteractionMachine.setup()
).
-
static
set_state
(state)¶ Sets the given
State()
as theInteractionMachine()
‘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 aSetupEvent()
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 toInteractionMachine.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:
- The current state is exited
(see
InteractionMachine.exit_state()
) - The destination state is enter
(see
InteractionMachine.enter_state()
)
- The current state is exited
(see
-
static
user
¶ A
User()
instance for the current user. Available when setup is complete (seeInteractionMachine.setup()
).
-
InteractionMachine.handle_message.
close
(msg)¶ Invoked when an inbound message is received with a
close
session event type. Emits aSessionCloseEvent()
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: - im (InteractionMachine) – the interaction machine emitting the event.
The event type is
session:new
.
-
class
SessionResumeEvent
(im)¶ Emitted when a new user message arrives for an existing user session.
Arguments: - im (InteractionMachine) – the interaction machine emitting the event.
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 anInteractionMachine()
with theApp()
returned byf
. Otherwise do nothing.If
f
is anApp()
subclass,new f()
is used to construct the application instance instead.Arguments: Returns the
InteractionMachine()
created ornull
if noInteractionMachine()
was created.Usually the return value is ignored since creating an
InteractionMachine()
attachs it to theapi
.