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.projectId | Returns project id. | String |
system.sessionId | Returns session id. | String |
system.internalSessionId | Returns internal 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.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: | 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.conversationTags | Returns all unique conversation tags gathered during current conversation. | List[String] |
system.conversationMetadata | Returns all unique (by key value) conversation metadata gathered during current conversation. | Object |
system.conversationContexts | Returns all unique contexts visited during current conversation. | List[String] |
system.getDefaultLanguage() | Return default language set in project | String |
system.getCurrentLanguage() | Return language set in current conversation | String |
system.setCurrentLanguage(language) | Set language in conversation, the same way as if Language block was used | Null |
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?
- Enable Automate's config property by setting
chatbots.admin.conversation-history-enabled: true
. - Enable system.lastConversations on organization form.
- 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")
Updated 4 months ago
Learn more about Expression language and its methods & APIs: