Each scenario's state can be activated by any of configured activator - a rule that tries to handle the user's request and find an appropriate state to activate. Activators function is a builder function of scenario that can be used to define which activators could activate the state.

How it works

state("launch") {
    activators {
        regex("/start")
        event(AlexaEvent.LAUNCH)
        intent(DialogflowIntent.WELCOME)
    }

    action {
        ...
    }
}

Here is a top-level state "launch" that can be activated by Alexa's LAUNCH event, Dialogflow's WELCOME intent or regular expression that matches any input with "/start" character sequence.

Learn more about different activators here.

globalActivators

By default activators will activate the state only if the parent state was activated previously. You can configure activators to be global - in this case the state can be activated by these activators as it was a top-level.

state("main") {
    state("inner") {
        activators {
            intent("some_intent")
        }
        globalActivators {
            event("activate_inner_state")
        }
    }
}

In the example above state "inner" could be activated by two different activators - intent activator with "some_intent" intent's name and event activator with "activate_inner_state" event's name. Once the intent activator could activate this state only in case the parent "main" state was activated previously, the event activator is a global and can activate "inner" state from everywhere.

fromState

Activators function accepts an optional state path from where it is available. It means that you can "override" a parent's state path to make a state available from some other state.

state("main") {
    state("inner") {
        activators("/other") {
            event("event1")
        }
    }
}

In the example above "inner" state can be activated once a dialogue is in state "/other". You can think about this as a mix-in feature.

Available activators

JAICF provides a set of available activators that can be used in your scenarios.

intent

Activates state if a NLU service has recognised the intent with the given name.

Generates an instance of IntentActivatorContext depending on the particular NLU service that has recognised an intent.

state("state1") {
    activators {
        intent("MyIntent")
        intent("AnotherIntent")
    }

    action {
        val intent = activator.intent?.intent
    }
}

anyIntent

Activates state if a NLU service has recognised any intent. Useful if you don't want to define exact intent names.

Generates an instance of IntentActivatorContext depending on the particular NLU service that has recognised an intent.

state("state1") {
    activators {
        anyIntent()
    }
}

event

Activates state if your bot has received a named event.

Generates EventActivatorContext instance. Learn more about event activator here.

state("state1") {
    activators {
        event(AlexaEvent.LAUNCH)
    }

    action {
        val event = activator.event?.event
    }
}

anyEvent

Activates state if your bot has received any event.

Generates EventActivatorContext instance.

state("state1") {
    activators {
        anyEvent()
    }
}

regex

Activates state if the user's query matches with the given regular expression.

Generates RegexActivatorContext that contains a matched pattern and matching result. Learn more about regex activator here.

state("state1") {
    activators {
        regex(".*")
        regex(Pattern.compile("[a-z]+"))
    }

    action {
        val pattern = activator.regex?.pattern
        val matcher = activator.regex?.matcher
    }
}

catchAll

Activates state if any query was received. Learn more about catchAll activator here.

state("state1") {
    activators {
        catchAll()
    }

    action {
        val query = request.input
    }
}

Writing custom activation rules

It's easy to implement your own activation rule inside scenario. See the example how to create an intent activator which activates all intens with common prefix:

// your activation rule
class IntentByPrefixActivationRule(
    private val commonPrefix: String
) : IntentActivationRule({
    it.intent.startsWith(commonPrefix) // your core activation logic
})

// your extension method which registers an activation rule
fun ActivationRulesBuilder.intentByPrefix(commonPrefix: String) = rule(IntentByPrefixActivationRule(commonPrefix))

And here is its usage example:

activators {
    intentByPrefix("smalltalk__")
}