Context
A context represents the conversation state of user sessions. Intents decorated with Context
attributes only get evaluated during the match process if the specified context name exists in user session. Contexts greatly help in removing ambiguities from conversations.
A context is composed of 2 parts.
Property | Description |
---|---|
Name | The name of the context. |
Lifespan | The total number of requests the context will exists for. The default lifespan is 5 requests. |
Additionally contexts also have an internal time span that measures their existence. By default a context stays active for 10 minutes. If either the lifespan (request count) or time span has been exceeded the context is removed from user session.
Usage
Lets assume that your application has a shutdown command but you wish to confirm with the user that he really wishes to shutdown the application.
[Expression("shutdown")]
public void Shutdown(Context context, Result result)
{
//Add a new "shutdown_confirmation" context.
context.Add("shutdown_confirmation", 2);
result.SendResponse("Are you sure?");
//Do something.
}
In the above code we created a new shutdown_confirmation
context with a lifespan of 2 requests. This newly created context will last for the next 2 requests.
[Expression("{yes}")]
[Entity(Sys.Positive)]
[Context("shutdown_confirmation")]
public void ShutdownConfirmed(Context context, Result result)
{
//Do something.
}
[Expression("{no}")]
[Entity(Sys.Negative)]
[Context("shutdown_confirmation")]
public void ShutdownCanceled(Context context, Result result)
{
//Do something.
}
When the user says Shutdown the bot will respond Are you sure?. If the user says yes the intent ShutdownConfirmed
will get invoked.
As we specified the lifespan of the context to be 2. The context becomes inactive after 2 user requests. Context can also be manually removed as shown in the code below.
context.Remove("shutdown_confirmation");
Parameters
An added context can carry multiple unique parameters during the course of its existence. These parameters can be used provide additional information regarding the underlying context.
Example
[Expression("turn on the air conditioner")]
public void TurnOnAC(Context context, Result result)
{
context.Add("air-con");
var acContext = context["air-con"];
acContext.Parameters.Add("temp", "medium");
}
OR
Using the Create()
method that creates and returns the newly created context item.
[Expression("{turn on} the air conditioner")]
[Entity("on")]
public void TurnOnAC(Context context, Result result)
{
var newConItem = context.Create("air-con");
newConItem.Parameters.Add("temp", "medium");
}
Conditonal Existence
After from counting the number of requests made to determine the lifespan of a context item. Developers may also pass a function while adding a new context item that determines for how long the context should stay active.
For example, when your user is watching a movie. You would want the commands pause and resume available until the movie is being played.
Example
[Expression("Play @movie-name")]
public void PlayMovie(Context context, Result result)
{
//Keep context active until movie is playing.
context.Add("movie-playback", () =>
{
return MoviePlayer.IsPlaying;
});
//Do something.
}
Note
Once a function is provided the value of the Lifespan
property is ignored. Also, once a context item goes inactive it is removed from user session.
Context Reversal
From version 3.4.0, developers can revert or undo the state of user context to the state that it was in 1 evaluation request ago. The state of the context is governed by the number of active context items that are present within a user context.
During a context reversal changes made by adding or removing context items are reverted and the lifespans of the newly changed context items are adjusted accordingly.
Note
The internal timespan of context items that are initially set based on provide Lifespan
are not effected by contextual undo.
The following code shows how you can call the Undo()
method to reverse a user's context state from within an intent.
[Expression("@sys.positive")]
[Context("go-backward")]
public void AcknowledgeCorrection(Context context, Result result)
{
//Reverse the user context state.
context.Undo();
//Send some response.
result.SendResponse("Alright, please specify your choice again.");
}
Note
You can only undo the last 5 collective changes on user context.