Controls in Virtual Agent API

  • Release version: Zurich
  • Updated March 12, 2026
  • 6 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of Controls in Virtual Agent API

    The Virtual Agent API offers a diverse set of controls to manage and customize conversational responses. These controls enable ServiceNow customers to design interactive and rich chatbot experiences by presenting information and collecting user input in varied formats.

    Show full answer Show less

    Response Output Controls

    • Output Text: Supports formatted text with options for bold, italic, lists, and links. Text can be marked as normal or secure.
    • Output Html: Allows embedding HTML content, including tables and links, with optional image conversion for display within conversations.
    • Output Image: Displays images by URL with optional alt text for accessibility.
    • Output Link: Presents clickable links with customizable headers and labels opening in new tabs.
    • Multi Link: Groups multiple links under a single header, each with labels, descriptions, contexts, and targets, facilitating organized navigation options.
    • Output Card: Displays rich card templates including large or small images with text, YouTube video cards, or record cards showing detailed information about ServiceNow records. Cards use JSON data to define content and support interactive smart links.
    • Multipart Output: Enables long or segmented content to be delivered in parts with navigation buttons to access additional content upon user interaction.

    User Input Controls

    • Input Text: Collects text input with options for required fields, secure input, and entity types like email or IP address.
    • Boolean: Provides a yes/no selection with customizable labels and render styles (data or buttons).
    • Picker: Offers single or multi-select options presented as lists or carousels, optionally paired with card templates for richer selection presentation.
    • Carousel: Specialized picker displaying image-based options with descriptions, supporting rich visual choice inputs.
    • Date, Time, DateTime: Collects date and/or time inputs with required field settings and entity type specifications.

    Conversation Control

    • StartConversation: Indicates the initiation of a conversation session within the Virtual Agent API, supporting conversational flow management.

    Practical Benefits for ServiceNow Customers

    These controls empower customers to create engaging, dynamic Virtual Agent dialogues tailored to diverse business needs. Whether displaying formatted content, multimedia, interactive cards, or collecting precise user inputs, these controls facilitate seamless integration into ServiceNow workflows. The ability to secure sensitive input, navigate multipart content, and use rich cards enhances user experience and improves automation efficiency.

    By leveraging these controls, customers can expect to build Virtual Agent conversations that are visually appealing, contextually relevant, and capable of capturing required user data effectively, ultimately driving better user satisfaction and operational productivity.

    Virtual Agent API provides you various controls to manage the responses in your conversation.

    The available controls in Virtual Agent API are:

    Output Text

    {
  "uiType": "OutputText",
  "group": "DefaultText",
  "value": "**bold**\n*italic*\n***bold italic***\n[Google](https://empcygiraffe6.service-now.com/va_link.do?token=77ee77ef77eSZGFlMTc3OWU5NzY2MTExMDUyNjFiMzQ3MTE1M2FmYjTvt6zvt5Qx77es77etWE1nS0ZLOElhU1FQYzhIajh2dmNmZz09WHdPTDYzV3ZpUWF1MGJwRlB0ZktUY29wVWt1UGVueUNIS1FkRHRyUW9idHlmVFZlRWJOODZyRjZYN0VQamxnWUV5WkhZSDRJaWFGWmJRZU1CaXZLYWhudnkwbDdvNFZsMlMzUUw4Q3VRTUJWMHhvTWlRLXZOQnh5M0hveVBuellNVmJCbGlka0RqNTAzVFVUQml0MTZzSnlUTVJoakdZektldXdoYXlM77eu77ev&target_url=https%3A%2F%2Fwww.google.co.in)\n\n- ***ul1***\n- ***ul2***\n\n\n1. ol1\n2. ol2\n\n",
  "maskType": "NONE | SECURE"
}
    Field Description
    value Contains the output text value.
    maskType 'NONE' indicates normal text and 'SECURE' indicates secure output text.

    Output Html

    {
  "uiType": "OutputHtml",
  "group": "DefaultOutputHtml",
  "style": "inline",
  "height": 0,
  "width": 0,
  "value": "<html>     <body>     <table>   <tr>     <th>Company</th>     <th>Contact</th>     <th>Country</th>   </tr>   <tr>     <td><a href=\"https://www.google.co.in\">Alfreds Futterkiste</a></td>     <td>Maria Anders</td>     <td>Germany</td>   </tr>   <tr>     <td>Centro comercial Moctezuma</td>     <td>Francisco Chang</td>     <td>Mexico</td>   </tr>   <tr>     <td><a href=\"https://www.google.co.in\">Ernest Handel</a></td>     <td>Roland Mendel</td>     <td>Austria</td>   </tr>   <tr>     <td>Island Trading</td>     <td>Helen Bennett</td>     <td>UK</td>   </tr>   <tr>     <td>Laughing Bacchus Winecellars</td>     <td>Yoshi Tannamuri</td>     <td><a href=\"https://www.google.co.in\">Canada</a></td>   </tr>   <tr>     <td>Magazzini Alimentari Riuniti</td>     <td>Giovanni Rovelli</td>     <td>Italy</td>   </tr> </table>     </body> </html> ",
  "imageUrl": "https://empcygiraffe6.service-now.com//api/now/v1/cs/media/zKFqUx0NJyVaFRJqzeRhFgeMsMo9211mCvrMgKzrRpTWqFJDrXLOadoYGC5CQnwr",
  "imageHeight": 217,
  "imageWidth": 501,
  "links": [
    {
      "link": "https://www.google.co.in",
      "label": "Alfreds Futterkiste"
    },
    {
       "link": "https://www.google.co.in",
       "label": "Ernest Handel"
    },
    {
       "link": "https://www.google.co.in",
       "label": "Canada"
    }
  ]
}
    Field Description
    value Contains the html value.
    imageUrl Contains the image of html if 'Html to image conversion required' is enabled on sys_cs_provider.
    imageHeight Contains the image height if 'Html to image conversion required' is enabled on sys_cs_provider.
    imageWidth Contains the image width if 'Html to image conversion required' is enabled on sys_cs_provider.
    links Contains links in the given html if 'Html to image conversion required' is enabled on sys_cs_provider.

    Output Image

    {
  "uiType": "OutputImage",
  "group": "DefaultOutputImage",
  "value": "https://adaptivecards.io/content/cats/1.png",
  "altText": "Image alt text"
 }
    Field Description
    value Contains the image url.
    altText Contains the alt text for the image (not mandatory).

    Output Link

    {
  "uiType": "OutputLink",
  "group": "DefaultOutputLink",
  "label": "ServiceNow",
  "header": "The world works with ServiceNow",
  "type": "link",
  "value": {
    "action": "https://empcygiraffe6.service-now.com/va_link.do?token=<token>&target_url=https%3A%2F%2Fwww.servicenow.com",
    "target": "_blank"
  }
}
    Field Description
    header Link Header
    label Link label
    value->action Link url

    Multi Link

    {
  "uiType": "GroupedPartsOutputControl",
  "group": "DefaultGroupedPartsOutputControl",
  "groupPartType": "Link",
  "header": "Multilink Header",
  "values": [
    {
      "action": "https://empcygiraffe6.service-now.com/va_link.do?token=<token>&target_url=https%3A%2F%2Fwww.link1.com",
      "description": "a short desc",
      "label": "link 1 label",
      "context": "KB",
      "target": "_blank"
    },
    {
      "action": "https://empcygiraffe6.service-now.com/va_link.do?token=<token>&target_url=https%3A%2F%2Fwww.link2.com",
      "description": "a short desc",
      "label": "link 2 label",
      "context": "ITSM",
      "target": "_blank"
    }
  ]
}
    Field Description
    header MultiLink control header
    values Links array
    Link structure in links array:
    Field Description
    label Link label
    action Link url
    description Link Description
    context Context or Taxonomy

    Output Card

    {
  "uiType": "OutputCard",
  "group": "DefaultOutputCard",
  "templateName": "<card-template>",
  "data": "<card-data-json>",
}
    Field Description
    templateName Card type or Card name
    data json representing card data.
    Note:
    The data field will be of type string. You need to parse it to use the data.
    Large Image With Text
    {
  "uiType": "OutputCard",
  "group": "DefaultOutputCard",
  "templateName": "Large image with text",
  "data": "{\"image\":\"https://adaptivecards.io/content/cats/1.png\",\"description\":\"Large image description\", \"dataNowSmartLink\":\"W9F4Ld8z\",\"title\":\"Large image\",\"imageAlt\":\"large image alt text\",\"url\":\"\",\"target\":\"_blank\"}",
  "smartLinksMetadata": {
    "W9F4Ld8z": {
      "type": "standard",
      "source": "",
      "target": "_blank"
    }
  }
}
    Small Image With Text
    {
  "uiType": "OutputCard",
  "group": "DefaultOutputCard",
  "templateName": "Small image with text",
  "data": "{\"image\":\"https://adaptivecards.io/content/cats/1.png\",\"description\":\"Small image with text description\",\"dataNowSmartLink\":\"i6CL61tN\",\"title\":\"Small image with text\",\"imageAlt\":\"small image alt text\",\"url\":\"\",\"target\":\"_blank\"}",
  "smartLinksMetadata": {
     "i6CL61tN": {
       "type": "standard",
       "source": "",
       "target": "_blank"
     }
  }
}
    Youtube
    {
  "uiType": "OutputCard",
  "group": "DefaultOutputCard",
  "templateName": "Youtube Video Card",
  "data": "{\"link\":\"https://empcygiraffe6.service-now.com/va_link.do?token=<token>&target_url=servicenow.com\",\"description\":\"The world works with ServiceNow\",\"id\":\"IWsGk-Kh5ko\",\"title\":\"ServiceNow\",\"url\":\"\",\"target\":\"_blank\"}"
}
    Record
    {
  "uiType": "OutputCard",
  "group": "DefaultOutputCard",
  "templateName": "Card",
  "data": "{\"sys_id\":\"0c5f3cece1b12010f877971dea0b1449\",\"subtitle\":\"INC0008001\",\"dataNowSmartLink\":\"VLzQTN88\",\"title\":\"Incident\",\"fields\":[{\"fieldLabel\":\"Number\",\"fieldValue\":\"INC0008001\"},{\"fieldLabel\":\"Short description\",\"fieldValue\":\"ATF:TEST2\"},{\"fieldLabel\":\"Caller\",\"fieldValue\":\"survey user\"}],\"table_name\":\"incident\",\"url\":\"https://empcygiraffe6.service-now.com/va_link.do?token=<token>target_url=https%3A%2F%2Fempcygiraffe6.service-now.com%2Fsp%3Fsys_id%3D0c5f3cece1b12010f877971dea0b1449%26id%3Dticket%26table%3Dincident\",\"target\":\"_blank\"}",
  "smartLinksMetadata": {
    "VLzQTN88": {
      "type": "standard",
      "source": "https://empcygiraffe6.service-now.com/sp?sys_id=0c5f3cece1b12010f877971dea0b1449&id=ticket&table=incident",
      "target": "_blank"
    }
  }
}

    Multipart Output

    {
  "uiType": "MultiPartOutput",
  "group": "DefaultMultiPartOutput",
  "navigationBtnLabel": "Click for more",
  "content": {
    "uiType": "OutputText",
    "value": "multipart text output",
    "maskType": "NONE"
  }
}
    Field Description
    navigationBtnLabel Navigation Button label
    content Represents the control defined with multipart.
    Note:
    • Content can be OutputText or OutputImage or OutputHtml or OutputLink or OutputCard.
    • You must send 'click_for_more' as response to move to the next part.

    InputText

    {
  "uiType": "InputText",
  "group": "DefaultText",
  "required": true,
  "nluTextEnabled": false,
  "entityType": "Text",
  "label": "enter something",
  "maskType": "NONE"
}
    Field Description
    label Input text label
    required True or false that indicates whether the control can be skipped or not.
    maskType NONE or SECURE.
    • NONE indicates normal input.
    • SECURE indicates secure input.
    entityType The input is text or email or IP address.
    nluTextEnabled Whether NLU is enabled at this node or not.

    Boolean

    {
  "uiType": "Boolean",
  "group": "DefaultPicker",
  "required": true,
  "nluTextEnabled": false,
  "entityType": "Boolean",
  "label": "select yes/no",
  "options": [
    {
       "label": "Yes",
       "value": "yes",
       "renderStyle": "data"
    },
    {
       "label": "No",
       "value": "no",
       "renderStyle": "data"
    }
  ]
}
    Field Description
    label Boolean control prompt
    required True or false that indicates whether the control can be skipped or not.
    maskType NONE or SECURE.
    • NONE indicates normal input.
    • SECURE indicates secure input.
    entityType Boolean
    nluTextEnabled Whether NLU is enabled at this node or not.
    options Boolean options
    Option structure in options array:
    Field Description
    label Option label
    value Option value
    renderStyle Data or button

    Picker

    {
  "uiType": "Picker",
  "group": "DefaultPicker",
  "required": true,
  "nluTextEnabled": false,
  "label": "Select an option",
  "itemType": "List",
  "style": "list",
  "multiSelect": false,
  "options": [
    {
      "label": "option 1",
      "value": "option 1",
      "renderStyle": "data",
      "enabled": false
    },
    {
      "label": "option 2",
      "value": "option 2",
      "renderStyle": "data",
      "enabled": false
    },
    {
      "label": "option 3",
      "value": "option 3",
      "renderStyle": "data",
      "enabled": false
    }
  ],
  "scriptedData": {
    "cardData": "{\"title\":\"Choice - Large image with text\",\"description\":\"Choice - Large image with text description\",\"image\":\"https://adaptivecards.io/content/cats/1.png\",\"imageAlt\":\"alt text\"}",
    "cardName": "Large image with text",
    "cardTemplate": "",
    "renderStyle": "card"
  }
}
    Field Description
    label Picker control prompt
    style List or carousel. Carousel indicates carousel control.
    required True or false that indicates whether the control can be skipped or not.
    maskType NONE or SECURE.
    • NONE indicates normal input.
    • SECURE indicates secure input.
    entityType Boolean
    nluTextEnabled Whether NLU is enabled at this node or not.
    options Boolean options
    scriptedData Represents a card to be displayed along with picker.
    Option structure in options array:
    Field Description
    label Option label
    value Option value
    renderStyle data or button
    scriptedData structure:
    Field Description
    cardName Template name
    cardData Card data as json string.

    Carousel

    {
  "uiType": "Picker",
  "group": "DefaultPicker",
  "required": true,
  "nluTextEnabled": false,
  "label": "select an image",
  "itemType": "Picture",
  "style": "carousel",
  "multiSelect": false,
  "options": [
    {
       "label": "name1",
       "description": "a description of value_1 item",
       "attachment": "https://adaptivecards.io/content/cats/1.png",
       "value": "value_1",
       "renderStyle": "data",
       "enabled": false
    },
    {
       "label": "name2",
       "description": "a description of value_2 item",
       "attachment": "https://adaptivecards.io/content/cats/1.png",
       "value": "value_2",
       "renderStyle": "data",
       "enabled": false
    },
    {
       "label": "name3",
       "description": "a description of value_3 item",
       "attachment": "https://adaptivecards.io/content/cats/1.png",
       "value": "value_3",
       "renderStyle": "data",
       "enabled": false
    }
  ],
  "scriptedData": null
}
    Field Description
    label Picker control prompt
    style List or Carousel. Carousel indicates carousel control.
    required True or false that indicates whether the control can be skipped or not.
    maskType NONE or SECURE.
    • NONE indicates normal input.
    • SECURE indicates secure input.
    entityType Boolean
    nluTextEnabled Whether NLU is enabled at this node or not.
    options Boolean options
    Option structure in options array:
    Field Description
    label Option label
    value Option value
    description description for the option
    attachment Picture or image for the option

    Date

    {
  "uiType": "Date",
  "group": "DefaultDate",
  "required": true,
  "nluTextEnabled": false,
  "entityType": "Date",
  "label": "test date"
}
    Field Description
    label Date control prompt
    required True or false that indicates whether the control can be skipped or not.
    entityType Date
    nluTextEnabled Whether NLU is enabled at this node or not.

    Time

    {
  "uiType": "Time",
  "group": "DefaultDate",
  "required": true,
  "nluTextEnabled": false,
  "entityType": "Time",
  "label": "Select time"
}
    Field Description
    label Time control prompt
    required True or false that indicates whether the control can be skipped or not.
    entityType Time
    nluTextEnabled Whether NLU is enabled at this node or not.

    DateTime

    {
  "uiType": "DateTime",
  "group": "DefaultDate",
  "required": true,
  "nluTextEnabled": false,
  "entityType": "Time",
  "label": "Select time"
}
    Field Description
    label Date and Time control prompt
    required True or false that indicates whether the control can be skipped or not.
    entityType Time
    nluTextEnabled Whether NLU is enabled at this node or not.

    StartConversation

    {
  "uiType": "ActionMsg",
  "actionType": "StartConversation",
  "conversationId": "e0494b2187332550326d0d05dabb350d"
}
    Field Description
    uiType ActionMsg
    actionType StartConversation

    Indicates that the conversation has started in Virtual Agent API.