Virtual Agent scripts
Use ServiceNow® Virtual Agent script methods and variables to write chat scripts, such as response, trigger, and flow scripts. Variables can also provide context for your live support topics and conversations.
Virtual Agent scripts can provide context for topics, such as retaining information about a user or a user's input. You can use this information to personalize a conversation, such as to present a scripted greeting or confirmation. Scripts can also specify certain actions to be performed on information that was obtained during a conversation. These actions can be used for creating or updating ServiceNow records.
Scripts run on the server in the scope in which a topic is defined. All scope protections apply. If you're developing a conversation for a scoped application, you must use the scoped API. You can use most APIs that run in server scripts.
User input and ServiceNow record variables
In Virtual Agent, the following variables are available for use in scripts that you create for a topic.
User input variables
When you add an input control to a topic, the system automatically creates a variable to store the user input (a string, Boolean value, and so on.). The syntax is
vaInputs.myvarwheremyvaris the name that you assigned to the input node.For example, a text input prompt with the name
First prompthas a system-defined variable calledvaInputs.first_prompt. Spaces in the name are replaced with an underscore character, and uppercase characters are changed to lowercase.ServiceNow record variables
If you create a script for a topic that queries a ServiceNow table, then the record object (GlideRecord) returned is automatically available for use in the topic. The variable syntax is
vaInputs.myvarwheremyvaris the record object. For details on querying ServiceNow tables to return a record object, see Querying tables in script.Use dot-walking in variables that contain a ServiceNow record to specify a particular field in the table. The syntax is
vaInputs.myvar.field. For details on dot-walking within a script, see Dot-walking examples.Accessing user input and ServiceNow record variables
Use vaInputs objects to access ServiceNow record variables in scripts. For example, the
vaInputs.myvar == "expected value". To access values from user inputs that are not records, usevaInputs.myvar.getValue().The following methods are available.
| Method | Description |
|---|---|
| vaInputs.myvar == "expected value" | Evaluates whether
|
| vaInputs.myvar.getValue\(\); | Returns the value. |
| vaInputs.myvar.getDisplayValue\(\); | Returns the display value if the stored value is not a ServiceNow record. For variables that contain ServiceNow records, this method returns the display value, as defined by the display field for that table. The following example shows the label and choice values for a user input. In this case, `myVar.getValue()` would return a value of 10, 20, or 30, while `myVar.getDisplayValue()` would return Apple, Orange, or Pear. Image omitted: va-value-vs-display.ong.png Label fields include Apple, Orange, and Pear for the choices. The values for each are 10, 20, and 30. |
| vaInputs.myvar.getDefaultValue\(\); | Returns the default value in a confirmation message. |
| vaInputs.myvar.getDefaultDisplayValue\(\); | Returns the display value for the default value in a confirmation message. |
| vaInputs.myvar.unbindEntity\(\); | Removes the value of input variables that the NLU prediction service slot-filled with extracted entities (unbinds it from the initial input value). For example, if the user decides to change their choice on a confirmation prompt, you can unbind the entity's value from the input variable. The user will then be prompted again when they loop back to the corresponding input node. Note: NLU must be enabled on the topic. In the Assistant Designer, select the Properties tab to set up NLU. For information about defining NLU entities, see Entities. |
Script variables
You can define script variables for information that is not stored in ServiceNow tables but that can be used to share that information elsewhere in a topic. Script variables are similar to workflow scratchpad variables that store primitives such as integers, Boolean values, or strings. A string value can be either a static or dynamic scripted value. Use the Variables sidebar to define script variables for a topic in Assistant Designer.
Sidebar in theAssistant Designer canvas for manually adding script variables that are used in topic scripts.
Note: Script variables are intended for use by topic authors with advanced scripting skills.
The variable syntax is vaVars.myvar, where myvar is the name that you assign to the variable. For example, you can assign a value to the variable using vaVars.myvar = value;. Unlike user input variables, script variables can be assigned values in a script.
For information about defining a script variable in a topic, see Define script variables for a topic.
Context variables
Context variables work in a global scope whereas system variables work within the scope of the topic. You can use context variables in system parameters within the web client URL. These variables can be used anywhere in the conversation using the vaContext object. Use these options to create links to Virtual Agent with predefined variables.
The following example link contains a parameter, sysparm_city=milan. In addition to opening a Virtual Agent conversation, using this link creates a variable called city with a value of milan. This variable can be accessed in a script using vaContext.city.
https://<instance>.service-now.com/$sn-va-web-client-app.do?sysparm_city=milan
A number of Live Agent variables are available for use in topic scripts. These variables include the following:
- application
- language
- portal
- search_text
- short_description
The variable syntax is vaContext.LiveAgent_myvar, where myvar is one of the available live agent context variables. Access the variable using vaContext.LiveAgent_myvar = value;.
To use Live Agent variables in topic scripts, open the topic in Assistant Designer. On the Properties tab, select the pencil icon next to Live Agent Variables to add them to the topic.
For information about live agent context variables that are included with Virtual Agent, see Live agent chat context variables.
| Method | Description |
|---|---|
| vaVars.global_utterance | Updates when skill picker renders and an utterance is typed in. |
vaSystem methods
You can use methods in the vaSystem object to do various tasks. Some of these tasks include the following:
- Attach images to records.
- Access the search string that was used to find the current topic.
- Verify that a live agent is available to receive a conversation.
- Connect the user to a live agent.
Note: The use of undocumented system methods is not recommended, as they are unsupported and may be discontinued or altered at any time without prior notice.
| Method | Description |
|---|---|
| vaSystem.applyLinkTemplate\(String sysId, String tableName, String actionName\) | Creates an external link that is specific to a portal. |
| vaSystem.attachRecordToConversation\(String tableName, String sysId\) | Attach ServiceNow records to the Related Tasks list in a Virtual Agent interaction record. These records are updated or created during a Virtual Agent conversation. |
| vaSystem.attachToRecord\(String mediaId, String tableName, String sysId\) | Attach an uploaded image to a ServiceNow record. The method uses the following parameters: - `mediaId`: The path for the image to be attached. To use an image entered by the customer, use `getValue()` on an image input variable. For example, `vaInputs.image_input.getValue()`. - `tableName`: A string that contains the name of the table. - `sysId`: The sys\_id of the record. |
| vaSystem.connectToAgent\(\) | Connects the customer to a live agent. For more information on this method, see Transferring Virtual Agent conversations to a live agent. |
| vaSystem.didConnectToLiveAgent\(\) | Returns a Boolean \(true or false\) value whether the current conversation was connected to a live agent. |
| vaSystem.getClosingMessage\(\) | Returns a closing message for a conversation from system property: com.glide.cs.general.closing_message. (The message is different for third-party messaging apps such as Microsoft Teams and Slack). |
| vaSystem.getConversationId\(\) | Returns the conversation ID of the current conversation. |
| vaSystem.getGreetingMessage\(\) | Returns a greeting message from UI Message with the key "Hi, I'm your Virtual Agent. Let me know how I can help you today." |
| vaSystem.getInteractionSysId\(\) | Returns the interaction ID of the current conversation. |
| vaSystem.getSearchText\(\) | Returns the last utterance typed by the user. |
| vaSystem.getTopicSelectionMessage\(\) | Returns a UI message with the key "What's your issue or request? Or take a look at what I can help with." (The message is different for third party messaging apps such as Microsoft Teams and Slack). This method is returned from the system property com.glide.cs.topic_picker_msg. |
| vaSystem.getTranscript\(\) | Gets the conversation transcript. |
| vaSystem.isLiveAgentAvailable\(\) | Checks whether a live agent is available to receive a conversation that is transferred from the bot. To transfer a conversation to a live agent, call this method before using `vaSystem.connectToAgent()`. |
| vaSystem.isLiveAgentConfigured\(\) | Returns whether live chat is enabled. |
| vaSystem.resetAllEntities\(\) | Resets all entities logged in the conversation. |
| vaSystem.sendBatchedMessages\(\) | Immediately sends queued messages. |
| vaSystem.sendSeparatorMessage\(\) | Sends a separator message line and returns the closing message from `getClosingMessage()`. |
| vaSystem.sendSystemMessage\(String message, Boolean showAvatar\) | Sends a system message and returns greetings message from `getGreetingMessage()`. |
| vaSystem.sendTopicPickerControl\(String topicSelectionMessage, String topicPickerButtonLabel\) | Sends a topic picker control with associated values for the message and "Show me everything" button label. |
| vaSystem.sendSkillPickerControl\(skillSelectionMessage, args\) | Sends the skill picker control to the user. The `skillSelectionMessage` is the message displayed before showing the picker.The `args` parameter allows additional configuration options: - `hideSkillDetails` hides the skill selection message. It defaults to `false`. - `hidePromotedTopics` hides promoted topics from the skill picker. It defaults to `false`. - `hideShowMeEverything` removes the "Show Me Everything" button from the skill picker. It defaults to `false`. - `showNoSkillsConfigured` displays a "No Skills Configured" message if there are no applicable skills. It defaults to `false`. - `appendPromotedSkillsToMsg` appends a bulleted list of promoted skills to the skill selection message. It defaults to `true`. |
| vaSystem.switchTopicByName\(\) | Enables the user to jump from the current conversation topic to the specified topic name. The X button is available, so that the user can end the conversation. After the topic ends, the user resumes the global topic. When the conversation ends, the user can select Click here to start a new conversation at the bottom of the chat window to restart the topic.The optional resumeBehavior parameter specifies how the conversation flow resumes, as follows:
If resumeBehavior is not specified, the default behavior for the instance is used. |
| vaSystem.switchTopicById\(sysid\) | This method is the sysid of sys_cb_topic, and enables the user to jump from the current conversation topic to the specified topic ID. The X button is available, so that the user can end the conversation. After the topic ends, the user resumes the global topic. When the conversation ends, the user can select Click here to start a new conversation at the bottom of the chat window to restart the topic.The optional resumeBehavior parameter specifies how the conversation flow resumes, as follows:
If resumeBehavior is not specified, the default behavior for the instance is used. |
| vaSystem.topicDiscovery\(String searchTextOverride, Boolean keywordImpl\) | Performs topic discovery based on term in the searchTextOverride parameter. The method uses the following parameters:- searchTextOverride: A string on which to run topic discovery. - keywordImpl: A Boolean that determines whether to use keywords. |
| Method | Description |
|---|---|
| sn\_cs.VASystemObject.getTranscriptById\(<conversation sysId>\) | Gets the transcript for the current Virtual Agent conversation. |
Parent Topic:Virtual Agent technical reference
Related topics
Domain separation and Virtual Agent
Virtual Agent interaction records