Virtual Agent scripts
-
- UpdatedDec 3, 2024
- 8 minutes to read
- Vancouver
- Virtual Agent
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 prompt has a system-defined variable called
vaInputs.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.
Table 1. vaInputs methods Method Description vaInputs.myvar == "expected value" Evaluates whether myvarmatches an expected value.Note: Values for user input variables are assigned using user input controls. These values can’t be changed in your scripts.- The Vancouver release supports additional data types. For more information, see Input data types in Virtual Agent topics.
- By default, the user variable is available and is a reference to the sys_user record for the user.
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, whilemyVar.getDisplayValue()would return Apple, Orange, or Pear.Figure 1. Example choice list 
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 Virtual Agent 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 Virtual Agent Designer.
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.
- 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 Virtual Agent 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.
vaSystem methods
- 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.
| Method | Description |
|---|---|
| sn_cs.VASystemObject.getTranscriptById(<conversation sysId>) | Gets the transcript for the current Virtual Agent conversation. |
On this page
Related Content
- Virtual Agent interaction records
Each time a Virtual Agent conversation occurs, an interaction record captures the entire conversation in the Interactions [interaction] table. The record includes all topic elements used in the conversation, as well as live agent transfers.
- Input data types in Virtual Agent topics
You can define inputs of commonly used Glide Virtual Agent (com.glide.cs.chatbot) data types in Virtual Agent Designer without writing a script. Define the input data type on the Start node of a custom control or topic block.
- NLU system entities
Use globally defined NLU entities to identify system information that Virtual Agent can extract from the conversation. You can define entities as "nodeless" input variables for a topic. These variables can be slot-filled from NLU service provider predictions or provided outside of the scope of the topic.
- Virtual Agent URL parameters
Virtual Agent provides various system parameters that admins can add to an instance URL to control how page content is rendered.
- Latency feedback in Virtual Agent
The com.glide.cs.message.processing.enabled system property notifies requesters whenever the generative AI large language model (LLM) is processing their request in the Virtual Agent web client and Now Assist panel.