Controls in Virtual Agent API

  • Release version: Zurich
  • Updated January 23, 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 in ServiceNow Zurich release offers a comprehensive set of controls to manage and customize conversation responses effectively. These controls allow you to deliver rich, interactive, and secure content to users, enhancing chatbot engagement and usability.

    Show full answer Show less

    Key Features

    • Output Controls: Various output types include:
      • Output Text: Supports formatted text (bold, italic, lists, links) with options for secure or normal display.
      • Output Html: Allows rendering HTML content, with optional image conversion and link extraction.
      • Output Image: Displays images via URLs with optional alternate text.
      • Output Link: Presents clickable links with customizable headers and labels, supporting external navigation.
      • Multi Link: Groups multiple links with headers, descriptions, and context tagging for taxonomy or categorization.
      • Output Card: Supports rich card templates including large/small images with text, YouTube video cards, and record cards that display ServiceNow record details with clickable smart links.
      • Multipart Output: Enables segmented content delivery with navigation buttons to view additional parts sequentially.
    • Input Controls: Facilitate user input with various control types:
      • Input Text: Text input with optional required flag and secure masking.
      • Boolean: Yes/No selection with configurable options and NLU integration toggle.
      • Picker: Single or multi-select lists or carousel styles, optionally displaying associated card data.
      • Date, Time, DateTime: Standard date and/or time selection inputs with required flags.
    • Conversation Control: An action message to start a conversation via the API, signaling conversation initiation within Virtual Agent.

    Practical Use for ServiceNow Customers

    ServiceNow customers can leverage these controls to build sophisticated Virtual Agent conversations that deliver formatted content, interactive cards, multimedia, and structured input collection. This flexibility enables tailored user experiences such as guided data collection, rich information display, and contextual navigation within chatbot interactions.

    Controls supporting secure content ensure sensitive data is handled appropriately, while multi-link and card groupings enhance content organization and clarity. Input controls with NLU toggles offer fine control over natural language processing at each conversation node. Overall, these controls empower customers to create dynamic, user-friendly, and secure Virtual Agent conversations aligned with their business processes.

    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 must 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.