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

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.

3. 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")