Session lifetime control

A session is a sequence of user requests and bot responses that have a common context.

There are several levels at which JAICP makes use of the separation of dialogs into sessions:

• Script development: the $session object is used to store session data. Its lifetime is limited by the session duration. When the session ends, this object is cleared.

• Analytics: sessions aggregate the history of bot conversations with users. They can be used for qualitative evaluation of bot performance.

  tip

  The $analytics built-in service allows labeling sessions programmatically for further analysis.

Automatic session control

The first session begins for the user when they first contact the bot. Their subsequent requests and bot responses are also recorded into this session until it ends.

caution

In all JAICP channels except for the phone channel, sessions with the same user do not end automatically.

This is best illustrated with an example. A user who is logged in to Telegram contacted the bot on May 18, and then again on June 22. If the developer did not specifically implement the script in a way that sessions should be ended after a timeout, JAICP would consider both interactions to belong to the same session. The duration of this session would be 35 days.

Sessions are always tied to a specific channel user, but not all channels require user authorization. In such channels, sessions cannot always be restored. For example, the chat widget relies on the waUserId_<project_ID> cookie to identify the user. If a person contacted the bot via the widget from two different browsers, the bot would treat them as two different users, each with their own session.

Manual session control

A project may have various conditions for ending a session, such as when:

• A timeout has expired.
• The user has been transferred to customer support.
• The device where the chat application is installed has been turned off.

It is the bot developer’s responsibility to determine when the old session should end and a new one should begin, and mark the appropriate places in the script by calling one of the session control methods:

Method	Description
$jsapi.startSession	This method starts a new session.
$jsapi.stopSession	This method stops the current session.

Session control in the phone channel

In the phone channel, session control works differently than in other channels. JAICP controls sessions automatically based on the principle that “one phone call is one session”:

• A new session is always started at the beginning of a phone call. This happens regardless of whether a new or existing customer is calling and whether $jsapi.startSession is called in the script.
• The session always ends when a customer terminates the phone call. If there is a call to $jsapi.stopSession at this point in the script, it is ignored.

tip

During a call, manual session control is not restricted. If you need to split one call into several sessions, JAICP allows doing so.