Thank you for your feedback.
Form temporarily unavailable. Please try again or contact docfeedback@servicenow.com to submit your comments.

Virtual Agent Designer user input controls

Log in to subscribe to topics and get notified when content changes.

Virtual Agent Designer user input controls

Use the collection of input controls provided by Virtual Agent Designer to prompt and capture information from the user in a conversation.

Common input properties

Each input control has the following common properties:

Input variable for the user response
Each control stores the user response in an input variable that is accessible from other controls within the same topic using the getValue() and getDisplayValue() methods. The variable name is based on the name that you assign to the input control. For example, if you assign the name First prompt to an input control, the variable name is first_prompt (lowercase, with an underscore character instead of a space). For more information on these methods, see Virtual Agent scripts.
Natural Language Understanding (NLU) entity properties
If NLU is enabled, the following properties display in the property sheet for the Text, Static Choice, Reference Choice, Boolean, Date Time, and Carousel input controls:
  • Associated entity: The entity that corresponds to the input variable for the control. You select the entity from the list of entities associated with the topic intent, as defined in the NLU model you are using for the topic. When Virtual Agent recognizes the entity value in user utterances and the value meets the entity prediction confidence threshold, Virtual Agent extracts the value. It stores the value in the input variable for the node (slot filling).
  • Enable NLU at Input Node: You can enable or disable NLU processing for a control. Selecting an Associated entity automatically activates the Enable NLU at Input Node switch. Users can enter text to select items or switch topics from this node when this switch is enabled.
  • Confirm Entity Recognition: You can enable or disable prompts that ask users to confirm the extracted entity. If the entity does not meet the Entity confidence threshold value (defined in the NLU Settings), Virtual Agent automatically prompts the user to accept or reject the extracted entity.
Default value
An input prompt can have a preset value that you define. This value can be either a string or a script that returns a string.
Confirmation message
This message can be either a text string or a script that returns a text string. If your input control provides users with a single-choice or default value selection, the selection that the user makes is automatically displayed in the conversation. For example, if you present a Boolean prompt, the user's selection (either yes or no) displays automatically.
Condition
A condition determines how or when the input control runs in the conversation flow. For example, you can provide a condition that enables only certain users to see a particular input prompt, while hiding the prompt from other users. To specify a condition, use either the no-code condition builder or a low-code script that contains a condition statement. The condition expression must evaluate to true or false. If the condition evaluates to true or if you do nor specify a condition, Virtual Agent always uses the control.

Text user input control

The Text user input control in a Virtual Agent topic prompts the user for a text string.

Table 1. Example Text user input control
Response properties Input prompt
Text user input control properties (original form)
Figure 1. Web UI Text user input prompt
Text user input prompt in the web UI
Figure 2. Slack Text user input prompt
Text user input prompt in Slack
Figure 3. Microsoft Teams Text user input prompt
Text user input prompt in Microsoft Teams
Figure 4. Workplace Text user input prompt
Text user input prompt in Workplace
Table 2. Text user input control properties
Property Description
Name Name that identifies this Text user input control node in the topic flow.
Variable Name Name of the variable that stores the user response to this prompt. The variable name is automatically created from the Name property.
Prompt Prompt or question to the user. The prompt can be either a text string or a script that returns text.
Associated Entity

[NLU only]

Entity associated with the input variable for this node. Select the entity from the list of entities associated with the topic intent.
Enable NLU at Input Node

[NLU only]

Switch for enabling or disabling Natural Language Understanding for this node. If enabled, users can enter text to answer questions and switch topics from this node.
Confirm entity recognition

[NLU only]

Switch for enabling or disabling prompts that ask users to confirm the extracted entity.
Acknowledge Message Message that verifies the user selection. The message can be either a text string or a script that returns text.
Default Value Predefined value for the user response to the question or prompt. The value can be either a text string or a script that returns text.
Confirmation Message Message that verifies the default or single-choice selection made by the user. The message can be either a text string or a script that returns text.
Condition No-code condition statement or low-code script that specifies a condition for presenting this prompt in the conversation. The condition must evaluate to true.
Note: Slack users can edit text previously entered in a conversation. However, because Virtual Agent processes messages as they are first entered, if a Slack user edits text input, such as a comment to update a case, Virtual Agent does not evaluate the edited update.

Static Choice user input control

Use the Static Choice user input control in a Virtual Agent topic to list predefined choices available to the user. A user can select only one item from a choice list.

Table 3. Example Static Choice user input control
Input properties List prompt
Static Choice user input control properties (original form)
Figure 5. Web UI Static Choice list prompt
Static Choice list prompt in the web UI
Figure 6. Slack Static Choice list prompt
Static Choice list prompt in Slack
Figure 7. Microsoft Teams Static Choice list prompt
Static Choice list prompt in Microsoft Teams
Figure 8. Workplace Static Choice list prompt
Static Choice list prompt in Workplace

Static Choice user input control properties

Table 4.
Property Description
Name Name that identifies this Static Choice user input control node in the topic flow.
Variable name Name of the variable that stores the user response to this prompt. The variable name is automatically created from the Name property.
Prompt Prompt or question to the user. The prompt can be either a text string or a script that returns text.
Associated Entity

[NLU only]

Entity associated with the input variable for this node. Select the entity from the list of entities associated with the topic intent.
Enable NLU at Input Node

[NLU only]

Switch for enabling or disabling Natural Language Understanding for this node. If enabled, users can enter text to answer questions and switch topics from this node.
Confirm Entity Recognition

[NLU only]

Enable or disable prompts that ask users to confirm the extracted entity. If the entity does not meet the Entity confidence threshold value (defined in NLU Settings), the bot automatically prompts the user to accept or reject the extracted entity.
Acknowledge Message Message that verifies the user selection. The message can be either a text string or a script that returns text.
Default value Predefined value for the user response to the question or prompt. The value can be either a text string or a script that returns text.
Confirmation Message Message that verifies the default or single-choice selection made by the user. The message can be either a text string or a script that returns text.
Condition No-code condition statement or low-code script that specifies a condition for presenting this prompt in the conversation. The condition must evaluate to true.
Choice List Setting For each choice, enter a Label and a Value. The Label is the text that appears to the user for that choice. The Value is a string that is stored in the variable when that choice is selected.
Use short phrases in your choice lists.
  • Slack has a limit of 30 characters for choice list labels.
  • Workplace has a limit of 20 characters for choice list labels.

Reference Choice user input control

Use the Reference Choice user input control in a Virtual Agent topic to dynamically create a list of available choices for your users. Create these choices by querying a table or by using a script to dynamically create them.

Example Reference Choice user input

Table 5.
Input properties List prompt
Reference choice list user input properties (original form)
Figure 9. Web UI Reference Choice list prompt
Reference Choice list prompt in the web UI

By default, the Web choice list displays 10 items per page. If there are more than 10 items, the end of the list provides a link for the user to display more results. An additional bubble displays the results next to the previous bubble. Users can scroll or click back in previous bubbles. If any item is two lines or longer, the text is truncated and appears with an ellipsis.

Figure 10. Slack Reference Choice list prompt
Reference Choice list prompt in Slack
Figure 11. Microsoft Teams Reference Choice list prompt
Reference Choice list prompt in Microsoft Teams
Figure 12. Workplace Reference Choice list prompt
Reference Choice list prompt in Workplace

Reference Choice user input control properties

Property Description
Name Name that identifies this Reference Choice user control node in the topic flow.
Variable Name Name of the variable that stores the user response to this prompt. The variable name is automatically created from the Name property.
Prompt Prompt or question to the user. The prompt can be either a text string or a script that returns text.
Associated Entity

[NLU only]

Entity associated with the input variable for this node. Select the entity from the list of entities associated with the topic intent.
Enable NLU at Input Node

[NLU only]

Switch for enabling or disabling Natural Language Understanding for this node. If enabled, users can enter text to answer questions and switch topics from this node.
Confirm Entity Recognition

[NLU only]

Switch for enabling or disabling prompts that ask users to confirm the extracted entity.
Acknowledge Message Message that verifies the user selection. The message can be either a text string or a script that returns text.
Default Value Predefined value for the user response to the question or prompt. The value can be either a text string or a script that returns text.
Confirmation Message Message that verifies the default or single-choice selection made by the user. The message can be either a text string or a script that returns text.
Condition No-code condition statement or low-code script that specifies a condition for presenting this prompt in the conversation. The condition must evaluate to true.
Choice List Setting
Reference Type Type of reference variable to be used. Select one of the following options:
  • Record: Returns records from the table selected. The values for these options are GlideRecord objects.
  • Script: Expression that returns an array of options.
Table If you selected Record as the Reference Type, select the table to be searched.
Choice Value Expression Select either Condition Builder or Script. Select Condition Builder to create a filter used to select a subset of records from the table. Select Script to enter a script that defines the enumeration list for the options (choice list) to be displayed. The name value pair is stored as a string object.
No records response message Message displayed to the user when the table search does not return any records. The message can be either a text string or a script that returns text.

Example Reference Choice list value expression

(function execute(table) {
        var options = [];
        var gr = new GlideRecord(table);
        gr.addEncodedQuery('active=true');
        gr.setLimit(5);
        gr.query();
        while(gr.next()) {
            options.push({ 'value': gr.getUniqueValue(), 'label': gr.getValue('short_description') });
        }
        return options;
})(table)

The script in the Choice Value Expression property defines and returns an array of choices. In the example, the script creates an array called options, and adds each record found in a GlideRecord query to this array. Each element in the array is given a value in the value and label keys using data from that GlideRecord. The Table property of the control defines the table used by the script. This example script uses gr.setLimit(5) to limit the number of records returned to 5. Using this method prevents returned records from creating an overly large choice list.

Table 6. Reference Choice control Value Expression keys
Key Description
value The value for the choice. When a user selects a choice from the control, this value is stored in the variable named in the Variable name property.
label The label that appears for this choice in the choice list.

Boolean user input control

Use the Boolean user input control in a Virtual Agent topic to present a Yes/No prompt to the user.

Table 7. Example Boolean user input control
Input properties Input prompt
Boolean user input control properties (original form)
Figure 13. Web UI Boolean user input prompt
Boolean user input prompt in the web UI
Figure 14. Slack Boolean user input prompt
Boolean user input prompt in Slack
Figure 15. Microsoft Teams Boolean user input prompt
Boolean user input prompt in Microsoft Teams
Figure 16. Workplace Boolean user input prompt
Boolean user input prompt in Workplace

Boolean user input control properties

Boolean user input controls prompt the user to answer a Yes/No question, and store the response as a string with a value of true or false. Use this value in topic utilities, such as the Decision utility, to branch the topic flow based on the answer.

Property Description
Name Name that identifies this Boolean user input control node in the topic flow.
Variable name Variable that stores the choice selected by the user. The variable name is automatically created from the Name property.
Prompt Prompt or question to the user. The prompt can be either a text string or a script that returns text.
Associated Entity

[NLU only]

Entity associated with the input variable for this node.
Enable NLU at Input Node

[NLU only]

Switch for enabling or disabling Natural Language Understanding for this node. If enabled, users can enter text to answer questions and switch topics from this node.
Confirm entity recognition

[NLU only]

Enable or disable prompts that ask users to confirm the extracted entity.
Acknowledge Message Message that verifies the user selection. The message can be either a text string or a script that returns text.
Default Value Predefined value for the user response to the question or prompt. The value can be either a text string or a script that returns text.
Confirmation Message Message that verifies the default or single-choice selection made by the user. The message can be either a text string or a script that returns text.
Condition No-code condition statement or low-code script that specifies a condition for presenting this prompt in the conversation. The condition must evaluate to true.

Date Time user input control

Use the Date Time user input control in a Virtual Agent topic to enable the user to select a calendar date, time (hours and minutes), or both.

Example Date Time user input control

Table 8.
Input properties Date Time prompt
DateTime input properties (original form)
Figure 17. Web UI Date Time prompt
Date Time prompt in the web UI
Figure 18. Slack Date Time prompt
Date Time prompt in Slack
Figure 19. Microsoft Teams Date Time prompt
Date Time prompt in Microsoft Teams
Figure 20. Workplace Date Time prompt
Date Time prompt in Workplace

Date and time selection for the Slack andWorkplace interfaces

The Slack and Workplaceinterfaces do not natively support a date selection widget. Date and time selection is instead done with the buttons that are supported in these interfaces.

The Date Time user input control prompts the user for a date, showing the current date and time. The user clicks the month, day, year, or time button to modify that value. The time and day fields prompt the user to type in a new value. The month and year fields show a set of buttons with the current and upcoming months or years. Select one of these buttons or type in a value to set the time or year.
Example of the Date Time picker used in the Slack and Microsoft Teams UI

Date Time picker properties

Date Time property Description
Name Name that identifies this Date Time user input control node in the topic flow.
Variable name Name of the variable that stores the user response to this prompt. The variable name is automatically created from the Name property.
Prompt Prompt or question to the user. The prompt can be either a text string or a script that returns text.
Associated Entity

[NLU only]

Entity associated with the input variable for this node. Select the entity from the list of entities associated with the topic intent.

Enable NLU at Input Node

[NLU only]

Switch for enabling or disabling Natural Language Understanding for this node. If enabled, users can enter text to answer questions and switch topics from this node.
Skip node if entity is fulfilled

[NLU only]

Enable or disable prompts that ask users to confirm the extracted entity.
Acknowledge Message Message that verifies the user selection. The message can be either a text string or a script that returns text.
Default Value Predefined value for the user response to the question or prompt. The value can be either a text string or a script that returns text.
Confirmation Message Message that verifies the default or single-choice selection made by the user. The message can be either a text string or a script that returns text.
Condition No-code condition statement or low-code script that specifies a condition for presenting this prompt in the conversation. The condition must evaluate to true.
Format Type of Date Time control to be displayed. Select one of the following formats:
  • Date: Shows only the monthly calendar for the user to select the date.
  • DateTime — Shows both a monthly calendar and time picker.
  • Time — Shows only the time picker for the user to select the time (hours and minutes).

Image picker user input control

Use the Image picker user input control in a Virtual Agent topic to prompt a user to upload an image. After the user uploads the image file, the image appears immediately in the Virtual Agent client.

Example Image picker user input control

Table 9. Image picker user input control example
Image properties Image picker prompt
Image picker user input properties
Figure 21. Web UI Image picker prompt
Image picker prompt in the web UI
Figure 22. Slack Image picker prompt
Image picker prompt in Slack
Figure 23. Microsoft Teams Image picker prompt
Image picker prompt in Microsoft Teams
Figure 24. Workplace Image picker prompt
Image picker prompt in Facebook Workplace

Image picker user input control properties

The image that can be uploaded must be in .jpg, .png, .bmp, .gif, .jpeg, or .ico file format. Although the image can be high resolution, the image displayed in the Virtual Agent client is scaled based on the aspect ratio. Images scale to fit within the chat window.

Table 10. Image picker properties
Property Description
Name The name that identifies the Image picker user input control node in the topic flow.
Variable name The name of the variable that stores the user response to this prompt. The variable name is automatically created from the Name property.
Prompt The prompt to the user asking them to upload an image. The prompt can be a text string that includes variables or a script that returns text.
Acknowledge Message The message that verifies the user selection. The message can be either a text string or a script that returns text.
Condition A no-code condition statement or low-code script that specifies a condition for using the Image picker user input control.

Using the Image picker control in different client interfaces

The process to select an image differs based on the Virtual Agent client interface. Use the following steps to select an image in the client interface of your choice.

Table 11. Image picker control in different client interfaces
Platform Steps to select an image
Web UI
  1. Click Click here to upload a file.
  2. Choose an image file from your local computer.
Slack
  1. Click the Green + icon.
  2. Select Your computer.
  3. Choose an image file from your local computer.
Microsoft Teams
  1. On your local computer, copy an image file.
  2. Paste the image file into the text input field in Microsoft Teams.
Workplace
  1. Click the image icon (Workplace image icon).
  2. Choose an image file from your local computer.
Feedback