System API
System API contains a set of general-purpose variables and methods. They provide:
- information on a current project, session and time,
- recent user inputs and bot responses,
- information on errors that occured, custom headers etc.
Full list of System API variables and methods
Variable/method | Description | Type |
---|---|---|
system.activeSessions | Returns the number of currently opened sessions (for the current project). | number |
system.author | Returns the user's name provided to API. | String |
system.concurrentRequests | Returns the number of concurrent requests issued to gateway from the current source. | number |
system.conversation | Returns the current conversation (up to the point of the method invocation) | List[Object] |
system.currentTime | Returns a date time value for the current date and time. | date time |
system.customHeaders | Returns custom HTTP headers. | Object |
system.escapeJson(value) | This method takes a String as an argument and returns the escaped version of that String. | String |
system.error | Returns a type of an error. | String or Object |
system.isError(errorType) | This method checks if an error is of the type provided as an argument. | boolean |
system.lastResponse | Returns contents of the last response of the bot. | String |
system.newUuid() | This method generates new UUID. | String |
system.sessionId | Returns session id. | String |
system.userInput | Returns the most recent user input (exactly what user wrote). | String |
system.source | Returns the source (channel) of conversation. | String |
system.activeSessions
Returns the number of currently opened sessions (for the current project).
system.activeSessions
// The result:
10
system.author
Returns the user's name provided to API.
It can be a phone number for calls, Facebook's account name for Facebook Messenger etc.
system.author
// The result for Facebook Messenger:
"Jane Doe"
// The result for a call:
"+99 999 888 777"
system.concurrentRequests
Returns the number of concurrent requests issued to gateway from the current source (eg. webchat, voice call, etc.).
system.concurrentRequests
// The result:
2
system.conversation
Returns the current conversation as an Array of Objects, in the following format:
[
{
"text": String,
"authorType": [Bot|Human],
"authorName": String,
"time": DateTime in ISO format
} 1..*
]
system.conversation
//The result
[
{
"text" : null,
"authorType" : "Human",
"authorName" : "Jan Kowalski",
"time" : "2022-10-12T15:20:49.603+02:00"
},
{
"text" : "How are you doing?",
"authorType" : "Bot",
"authorName" : "Bot",
"time" : "2022-10-12T15:20:49.628+02:00"
},
{
"text" : "fine",
"authorType" : "Human",
"authorName" : "Jan Kowalski",
"time" : "2022-10-12T15:20:51.517+02:00"
}
]
system.currentTime
Returns a DateTime value for the current date and time.
The value of system.currentTime
is a DateTime value and not a String, so the methods listed in DateTime API can be applied directly to it.
system.currentTime
// The result - the current timestamp, for example:
2021-07-09 08:08
system.customHeaders
Returns custom HTTP headers (all names are lowercase).
system.customHeaders["x-forwarded-for"]
// The result:
{
"x-request-id" : "RBS-FQS-QMV",
"x-forwarded-for" : "31.61.183.246"
}
system.escapeJson(value)
This method takes a String as an argument and returns the escaped version of that String, so it can be used as an input parameter for integration that uses it inside of a JSON body.
system.escapeJson(system.userInput)
// The result, assuming that user input is a quotation mark:
\"
system.error
Returns a type of error that occurred but has been recovered by an Error Handling context.
Types of errors:
- KnowledgeBaseError.ItemNotFound
- KnowledgeBaseError.InvalidString
- ModelError
- ExpressionError
system.error
// The result if Knowledge Base item is missing:
KnowledgeBaseError.ItemNotFound
system.isError(errorType)
This method checks if an error is of the type provided as an argument. Returns true
or false
.
KnowledgeBaseError - isError("KnowledgeBaseError") returns true for all suberrors
KnowledgeBaseError.ItemNotFound - requested knowledge base item doesn't exist
KnowledgeBaseError.InvalidString - requested knowledge base item is a String but it's not a valid
ModelError - model error, e.g. invalid context reference, infinite loop etc.
ExpressionError - expression evaluation error (e.g. invalid function name)
system.lastResponse
Returns contents of the last response of the bot.
It is overwritten with a new value any time the bot responses.
system.lastResponse
// The result
"Hello, my name is Bianca. I'm a bot."
system.newUuid()
This method generates new UUID (universally unique identifier).
system.newUuid()
// The result:
96713ed3-9cb0-4ce5-95fe-150de3a96fe2
system.sessionId
Returns session id, has the same value as suid defined in Gateway API.
system.sessionId
// The result:
webchat_49juk26v32fz0ucle93o3d
system.userInput
Returns the most recent user input (exactly what the user wrote).
It does not trigger NLU classification, it just repeats what the user wrote. It is overwritten with a new value any time we request user input.
It is frequently used for setting up conditions without using NLU, eg. when using quick replies in chatbots. For example, the condition below is fulfilled only when the user types exactly "test".
system.userInput
// The result:
"Hello bot, I'm a human."
system.source
Returns the source (channel) of a conversation, ex. "facebook", "phone", "twitter", etc.
system.source
// The result:
"facebook"
Updated 4 months ago
Learn more about Expression language and its methods & APIs: