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/methodDescriptionType
system.activeSessionsReturns the number of currently opened sessions (for the current project).number
system.authorReturns the user's name provided to API.String
system.concurrentRequestsReturns the number of concurrent requests issued to gateway from the current source.number
system.conversationReturns the current conversation (up to the point of the method invocation)List[Object]
system.currentTimeReturns a date time value for the current date and time.date time
system.customHeadersReturns 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.errorReturns 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.lastResponseReturns contents of the last response of the bot.String
system.newUuid()This method generates new UUID.String
system.sessionIdReturns session id.String
system.userInputReturns the most recent user input (exactly what user wrote).String
system.sourceReturns 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"

What’s Next

Learn more about Expression language and its methods & APIs: