---
sourceDocument: Zurich Conversational Interfaces
sourceDocumentLink: https://www.servicenow.com/docs/r/zurich/conversational-interfaces

 Release :

    - zurich

ft:locale :

    - en-US

ft:publication_title :

    - Zurich Conversational Interfaces

ft:clusterId :

    - convint

bundleId :

    - convint

workflow :

    - Platform


---

# Virtual Agent scripts

# Virtual Agent scripts {#ariaid-title1}

* Release version: Zurich
* 
* Updated July 31, 2025
* 
* ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 9 minutes to read

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 {#virtual-agent-scripts__section_ssh_pxw_sdb}

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.myvar` where
    `myvar` is the name that you assigned to the input node.

    For example, a text input prompt with the name <kbd class="ph userinput">First prompt</kbd> 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.myvar` where
    `myvar` is the record object. For details on querying ServiceNow tables to return a record object, see [Querying tables in script](https://www.servicenow.com/docs/access?context=c_UsingGlideRecordToQueryTables&version=zurich&pubname=zurich-api-reference&ft:locale=en-US).

    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](https://www.servicenow.com/docs/access?context=dot-walking-examples&version=zurich&pubname=zurich-platform-user-interface&ft:locale=en-US).

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, use
    `vaInputs.myvar.getValue()`.

    The following methods are available.  
    {#virtual-agent-scripts__table_uht_pzs_cpb__entry__2}

    | Method | Description |
    |-|-|
    | vaInputs.myvar == "expected value" | Evaluates whether `myvar` matches 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 Zurich release supports additional data types. For more information, see [Input data types in Virtual Agent topics](https://www.servicenow.com/docs/DVQclOrgfECH7FR6cq30~g "You can define inputs of commonly used Glide Virtual Agent (com.glide.cs.chatbot) data types in Assistant Designer Asset library without writing a script. Define the input data type on the Start node of a custom control or topic block."). * By default, the user variable is available and is a reference to the sys_user record for the user. {#virtual-agent-scripts__ul_dsz_rbt_cpb} |
    | 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. 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 Assistant Designer Asset library, select the Properties tab to set up NLU. For information about defining NLU entities, see [Entities](https://www.servicenow.com/docs/access?context=entities&version=zurich&pubname=zurich-intelligent-experiences&ft:locale=en-US). |
    [Table 1. vaInputs methods]

    {#virtual-agent-scripts__table_uht_pzs_cpb}

## Script variables {#virtual-agent-scripts__section_kpv_qxj_12b}

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 Asset library.  
Figure 2. Variables sidebar  
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](https://www.servicenow.com/docs/E8Q5diq99toCf2ElgNg01g "Use the Variables sidebar to define script variables for a topic. Script variables can store information that is not found in ServiceNow tables. This information can then be shared elsewhere in a topic.").

## Context variables {#virtual-agent-scripts__section_mc5_tvw_22b}

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:

* <var class="keyword varname">application</var>
* <var class="keyword varname">language</var>
* <var class="keyword varname">portal</var>
* <var class="keyword varname">search_text</var>
* <var class="keyword varname">short_description</var>
{#virtual-agent-scripts__ul_nvm_krg_rwb}

The variable syntax is `vaContext.LiveAgent_myvar`, where `myvar` is one of the available [live agent context variables](https://www.servicenow.com/docs/wta7E9g5gFHI2uf896wmeA "Use chat context variables to pass certain information from the topic to share with a live agent or to control how bot conversations are routed to live agents. Virtual Agent includes some default variables, and you can define new ones."). Access the variable using `vaContext.LiveAgent_myvar = value;`.

To use Live Agent variables in topic scripts, open the topic in Assistant Designer Asset library. 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](https://www.servicenow.com/docs/wta7E9g5gFHI2uf896wmeA "Use chat context variables to pass certain information from the topic to share with a live agent or to control how bot conversations are routed to live agents. Virtual Agent includes some default variables, and you can define new ones.").  
{#virtual-agent-scripts__table_evl_vbd_cfc__entry__2}

| Method | Description |
|-|-|
| vaVars.global_utterance | Updates when skill picker renders and an utterance is typed in. |
[Table 2. vaVars methods]

{#virtual-agent-scripts__table_evl_vbd_cfc}

## vaSystem methods {#virtual-agent-scripts__section_bdc_wtr_h2b}

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.
{#virtual-agent-scripts__ul_rgh_w31_fpb}  
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.
{#virtual-agent-scripts__table_xvn_c5r_h2b__entry__2}

| 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. {#virtual-agent-scripts__ul_dlj_4yr_h2b} |
| vaSystem.connectToAgent() | Connects the customer to a live agent. For more information on this method, see [Transferring Virtual Agent conversations to a live agent](https://www.servicenow.com/docs/kM5GQxC_N8kCNs39aXGGPQ "Manage live chat support, including the chat support interface used when a Virtual Agent conversation is transferred 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`. {#virtual-agent-scripts__ul_lwk_dgx_22c} |
| 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=resume, Virtual Agent resumes the calling topic. * If resumeBehavior=skip, Virtual Agent skips the calling topic. {#virtual-agent-scripts__ul_x2k_rxk_gtb} 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=resume, Virtual Agent resumes the calling topic. * If resumeBehavior=skip, Virtual Agent skips the calling topic. {#virtual-agent-scripts__ul_hwt_21l_gtb} 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. {#virtual-agent-scripts__ul_rq2_zst_ssb} |
[Table 3. Methods used in Virtual Agent topic scripts]

{#virtual-agent-scripts__table_xvn_c5r_h2b} {#virtual-agent-scripts__table_mqd_wqp_1jb__entry__2}

| Method | Description |
|-|-|
| sn_cs.VASystemObject.getTranscriptById(\<conversation sysId\>) | Gets the transcript for the current Virtual Agent conversation. |
[Table 4. Method that can be used outside Virtual Agent topics]

{#virtual-agent-scripts__table_mqd_wqp_1jb}
**Related concepts**   

* [Domain separation and Virtual Agent](https://www.servicenow.com/docs/EZB4zYkm69P8ACJeRZICSA "Domain separation is supported in the Virtual Agent application. Domain separation enables you to separate data, processes, and administrative tasks into logical groupings called domains. You can control several aspects of this separation, including which users can see and access data.")
* [Virtual Agent interaction records](https://www.servicenow.com/docs/9Yuui2WilLR6JMN0GpD_LQ "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.")  
**Related reference**   

* [Virtual Agent roles](https://www.servicenow.com/docs/X6DWWsnEva0DLRP_BCa_Vw#VA-roles "Virtual Agent adds several roles for users operating as Virtual Agent administrators.")
* [Input data types in Virtual Agent topics](https://www.servicenow.com/docs/DVQclOrgfECH7FR6cq30~g "You can define inputs of commonly used Glide Virtual Agent (com.glide.cs.chatbot) data types in Assistant Designer Asset library without writing a script. Define the input data type on the Start node of a custom control or topic block.")
* [NLU system entities](https://www.servicenow.com/docs/2CNpKmFRa00tWrNIFHF0hw "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](https://www.servicenow.com/docs/DVa3NxRHrKCsItHIQBxNBw "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](https://www.servicenow.com/docs/CKgT89fJ5Xvv4eNIK64YwA "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 chat widget and ServiceNow Otto panel.")