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.projectIdReturns project id.String
system.sessionIdReturns session id.String
system.internalSessionIdReturns internal session id.String
system.userInputReturns the most recent user input (exactly what user wrote).String
system.sourceReturns the source (channel) of conversation.String
system.lastConversationsReturns last 10 finished conversations made by a current author. Conversations are sorted by the end date in descending order (newest conversations are first). Returned value is as an array of objects in the following format:List[Object]
system.sleep(time)This method can be used to pause the execution of the current flow for a specified time in milliseconds.Null
system.conversationTagsReturns all unique conversation tags gathered during current conversation.List[String]
system.conversationMetadataReturns all unique (by key value) conversation metadata gathered during current conversation.Object
system.conversationContextsReturns all unique contexts visited during current conversation.List[String]
system.getDefaultLanguage()Return default language set in projectString
system.getCurrentLanguage()Return language set in current conversationString
system.setCurrentLanguage(language)Set language in conversation, the same way as if Language block was usedNull

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

๐Ÿ“˜

Tags, metadata and contexts are present from version 239.

Returns the current conversation as an Array of Objects. Tags, metadata and contexts are non-empty only for the last bot's response in the round. Returned value is as an array of objects in the following format:

[
  {
    "text": String,
    "authorType": [Bot|Human],
    "authorName": String,
    "time": DateTime in ISO format,
    "tags": List[String],
		"metadata": Object,
		"contexts": List[String]
  } 1..*
]
system.conversation

//The result
[
  {
    "text" : null,
    "authorType" : "Human",
    "authorName" : "Jan Kowalski",
    "time" : "2022-10-12T15:20:49.603+02:00",
    "tags": [],
    "contexts": [],
    "metadata": {} 
  },
  {
    "text" : "How are you doing?",
    "authorType" : "Bot",
    "authorName" : "Bot",
    "time" : "2022-10-12T15:20:49.628+02:00",
    "tags": ["tag_greeting"],
    "contexts": ["greeting"],
    "metadata": { "forename": ["Jan"] } 
  },
  {
    "text" : "fine",
    "authorType" : "Human",
    "authorName" : "Jan Kowalski",
    "time" : "2022-10-12T15:20:51.517+02:00",
    "tags": [],
    "contexts": [],
    "metadata": {} 
  }
]

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.projectId

Returns project id, has the same value as uuid defined in Gateway API.

system.projectId

// The result: 
b7e6d3e1-7901-49e6-aebd-8cbcae929f7a

system.sessionId

Returns session id, has the same value as suid defined in Gateway API.

system.sessionId

// The result: 
webchat_49juk26v32fz0ucle93o3d

system.internalSessionId

Returns internal session id, which matches Automate Session ID in the Conversations module. It is generated by Automate for a single conversation with Bot. It is regenerated when Bot reaches the end of conversation and starts from the beginning, even when Gateway API is called with the same suid.

system.internalSessionId

// The result: 
int_sid_20231221_44356707_sPuebuLRhL

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"

system.lastConversations

Returns last 10 finished conversations made by a current author. Conversations are sorted by the end date in descending order (newest conversations are first). Returned value is as an array of objects in the following format:

[
  {
    "startDate": DateTime,
    "endDate": DateTime,
    "tags": List[String],
    "metadata": Map[String, List[String]],
    "sessionId": String
  } 0..10
]
system.lastConversations

[
	{
		"endDate" : "2023-06-01T14:57:49.481Z",
		"tags" : [
			"superTag"
		],
		"sessionId" : "webchat_qmosivsitwkqnxdccfxa7",
		"metadata" : {
			"bestCompany" : [
				"SentiOne"
			]
		},
		"startDate" : "2023-06-01T14:57:49.481Z"
	},
	{
		"endDate" : "2023-06-01T14:53:57.871Z",
		"tags" : [
			"superTag"
		],
		"sessionId" : "webchat_b85i1h11o5rt0j11tyvmol",
		"metadata" : {},
		"startDate" : "2023-06-01T14:53:57.871Z"
	},
	{
		"endDate" : "2023-06-01T14:50:41.758Z",
		"tags" : [],
		"sessionId" : "webchat_o54ros0yob8jzj1i727fhs",
		"metadata" : {},
		"startDate" : "2023-06-01T14:50:41.758Z"
	}
]

How to enable system.lastConversations?

  1. Enable Automate's config property by setting chatbots.admin.conversation-history-enabled: true.
  2. Enable system.lastConversations on organization form.

  1. You can use system.lastConversations in your flow.

๐Ÿšง

Please note that disabling conversation history wonโ€™t take immediate effect on already published projects. If you want to have that feature disabled on existing projects, you have to republish them.

Error when system.lastConversations is not enabled

When system.lastConversations is not enabled, following error is returned

system.sleep(time)

This method can be used to pause the execution of the current flow for a specified time in milliseconds. The maximum time for a single execution is 5 seconds. Total sleep time when handling a single user message can't exceed 20 seconds.

system.sleep(1000)

// Sleeps for 1 second and returns:
null

๐Ÿšง

Please note that this method is not available in JavaScript.

system.conversationTags

๐Ÿ“˜

Available from version 239.

Returns all unique conversation tags gathered during current conversation.

system.conversationTags

[
  "tag_say1",
  "tag_say2"
]

system.conversationMetadata

๐Ÿ“˜

Available from version 239.

Returns all unique conversation metadata gathered during current conversation.

system.conversationMetadata

[
  { "name": ["Albert"] },
  { "hobbies": ["Science", "Quotes"] }
]

system.conversationContexts

๐Ÿ“˜

Available from version 239.

Returns all unique contexts visited during current conversation.

system.conversationContexts

[
	"greeting",
  "introduction"
]

system.getDefaultLanguage()

Returns default language set for project

system.getDefaultLanguage()

en

system.getCurrentLanguage()

Return language used currently in flow

system.getCurrentLanguage()

pl

system.setCurrentLanguage(code)

Manually sets language in conversation, the same way as if Language block was used

system.setCurrentLanguage("de")

Whatโ€™s Next

Learn more about Expression language and its methods & APIs: