Default input and output rich controls for a custom chat integration

  • Release version: Zurich
  • Updated July 31, 2025
  • 3 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 Default input and output rich controls for a custom chat integration

    ServiceNow’s Zurich release provides a set of default input and output rich controls designed to be mapped within thesyscscustomadapterconfigtable for custom chat integrations. Proper mapping and outbound transformer implementation of these controls are essential to ensure that end users receive appropriate responses and a seamless chat experience. Missing transformers can result in unsatisfactory interactions with no response delivered.

    Show full answer Show less

    Key Controls and Their Purpose

    • ActionRichControl: Manages conversation events and action messages such as spinner controls, topic switching, and live agent transitions. A single outbound transformer can handle all messages under this control, with no inbound transformer needed. It also supports an agentInfo parameter indicating messages sent from live agents.
    • DefaultPicker: Maps to File Picker, Topic Picker, and Boolean controls, allowing options with labels, values, descriptions, attachments, and an optional ordering parameter to define the display sequence of promoted topics.
    • DefaultText: Supports input and output text, file uploads, and pictures, with attributes for required status, natural language understanding (NLU) enablement, item type, data masking, and labeling.
    • DefaultDate: Handles date, time, and datetime inputs with support for required flags and NLU.
    • DefaultOutputLink: Used for link responses, including label, header, and action URL properties.
    • DefaultOutputImage: Represents image responses with a URL value.
    • DefaultOutputCard: Displays card responses using a template name and JSON data payload.
    • DefaultOutputHtml: Renders inline HTML content with configurable style, size, and HTML value.
    • DefaultOutputTable: Shows tabular data with headers, labels, navigation controls, and row data arrays.
    • DefaultGroupedPartsOutputControl: Supports multi-response grouped controls, such as links with descriptive labels and context information.
    • DefaultMultiPartOutput: Provides multipart responses that can include embedded HTML content and navigation labels.
    • DefaultCustomControl: Allows integration of user-defined custom controls with parameters for naming, input/output behavior, component definitions, and serialized control data.

    Practical Implications for ServiceNow Customers

    When configuring custom chat integrations, mapping these default rich controls correctly ensures that user interactions are handled appropriately, and responses are formatted as expected. Customers should implement outbound transformers for these controls to enable message delivery. Leveraging these predefined controls helps streamline development, maintain consistency across channels, and support a rich conversational experience within Virtual Agent Designer environments.

    Input and output rich controls must be mapped to your custom chat integration in the Custom Adapter Configurations [sys_cs_custom_adapter_config] table. If a rich control is missing an outbound transformer implementation, a response is not served to the end user and that user may get an unsatisfactory chat experience.

    The following default rich controls map to input and output rich controls. The uiType parameter refers to a topic control used to build conversations in Virtual Agent Designer.

    Table 1. Default input and output rich controls
    Rich control Description
    ActionRichControl This component handles the different events and actions that occur in a conversation. Some actions may not apply to all channels. For example, StartSpinnerActionMsg is ignored in SMS.

    ServiceNow® Virtual Agent produces the following types of action messages through this framework. The custom chat interface only recognizes certain action message types.

    • SeparatorActionMsg ||actionMsg instanceof
    • SystemActionMsg ||actionMsg instanceof
    • TopicFinishedActionMsg ||actionMsg instanceof
    • SwitchToVirtualAgentActionMsg ||actionMsg instanceof
    • SwitchConversationActionMsg ||actionMsg instanceof
    • ChatSubHeaderActionMsg ||actionMsg instanceof
    • StartSpinnerActionMsg ||actionMsg instanceof EndSpinnerActionMsg
    • SubscribetoSupportQueue ||actionMsg instanceof
    • SubscribeToChatPresence ||actionMsg instanceof
    • SwitchToLiveAgentActionMsg ||actionMsg instanceof

    ActionRichControl wraps these messages inside the actionMsg element. So, a single outbound transformer for ActionRichControl can handle all of these messages. There is no need for an inbound transformer for this component.
    agentInfo parameter If the rich control is sent from a live agent, then the agentInfo attribute is added to the rich control.
    Example:
    {
     uiType: "someType",
     group: "someGroup"
     agentInfo: { sentFromAgent: true }  // please note that this object may contain more info in subsequent releases.
     ...
}
    DefaultPicker Maps to File Picker, Topic Picker, and Boolean controls.
    Example:
    {
    uiType: "Picker/TopicPicker/Boolean",
    group: "DefaultPicker",  
    nluTextEnabled: true/false,
    promptMsg: "", // optional (needed for TopicPicker)
    label: "The question for the list",   // always filled
    itemType: "Picture/List"  // needed to user key to expect picture attached
    options: [
        {
            label: "display label prompt",
            value: "the value required to satisfy the question",
            description: "a description of value_1 item"
	    attachment: "www.foo",
            enabled: true/false
        }, 
	...
    ]
}

    The optional order parameter lets you specify the order in which promoted topics should display. For example:

    "options": [
    {
      label: "Check IT Ticket Status",
      value: "55720b465bf0201024f11fc40a81c72d",
      order: 100,
      enabled: true
    },
    {
      label: "Live Agent Support",
      value: "ce2ee85053130010cf8cddeeff7b12bf",
      order: 200,
      enabled: true
    },
    {
      label: "Open IT Ticket 2",
      value: "2a46cffbc7602010v088bbf603c260a7",
      order: 300,
      enabled: true
    }
]
    DefaultText Maps to Input Text, Output Text, and File Upload controls.
    Example:
    {
    uiType: "InputText/OutputText/FileUpload/Picture",
    group: "DefaultText", 
    required: true/false,
    nluTextEnabled: true/false,
    itemType: "file/image/inputtext/outputtext",
    maskType: "SECURE/SENSITIVE/NONE"  // null except for InputText/OutputText
    label: "The Question?"        
}
    DefaultDate Maps to Date and Time controls.
    {
    uiType: "Date/DateTime/Time",
    group: "DefaultDate", 
    required: true/false,
    nluTextEnabled: true/false,   
    label: "The Question?"
     
}
    DefaultOutputLink Maps to link response controls.
    Example:
    {
    uiType: "OutputLink",
    group: "DefaultOutputLink",
    label: "link label",
    header: "link header",
    type: "link",
    value: {
        action: "www.foo",
    }	
}
     
}
    DefaultOutputImage Maps to image response controls.
    Example:
    {
    uiType: "OutputImage",
    group: "DefaultOutputImage",
    value: "www.foo"
}
    DefaultOutputCard Maps to card response controls.
    Example:
    {
    uiType: "OutputCard",
    group: "DefaultOutputCard",
    templateName: "Card",
    data: "some json data string"
}
    DefaultOutputHtml Maps to HTML response controls.
    Example:
    {
    uiType: "OutputHtml",
    group: "DefaultOutputHtml",
    style: "inline",
    height: 100,
    width: 100,
    value: "<div>html</div>"
}
    DefaultOutputTable Maps to table response controls.
    Example:
    {
    uiType: "OutputTable",
    group: "DefaultOutputTable",
    label: "Table Title",
    headers: ["Column 1", "Column 2"],
    navigationBtnLabel: "See next",
    data: [
        ["foo1", "foo2"],
        ["bar1", "bar2"]
    ]
}
    DefaultGroupedPartsOutputControl Maps to multi-response controls.
    Example:
    {
    uiType: "GroupedPartsOutputControl",
    group: "DefaultGroupedPartsOutputControl"
    groupPartType: "Link",
    header: "header message",
    values: [
	{
	    action: "www.foo",
	    description: "description",
	    label: "link_1 label",
	    context: "ITSM"
	},
	...
    ]
}
    DefaultMultiPartOutput Maps to multi-response controls.
    Example:
    {
    uiType: "MultiPartOutput",
    group: "DefaultMultiPartOutput"
    navigationBtnLabel: "Go next",
    content: {
        uiType: "OutputHtml",
        style: "inline",
        type: "html",
        height: 100,
        width: 100,
        value: "<div>html</div>"
     }
}
    DefaultCustomControl Maps to custom controls.
    Example:
    {
    uiType: "CustomControl",
    group: "DefaultCustomControl",
    name: "The name of the Custom Control (sys_cs_custom_control.name)",
    required: true/false,
    uxComponentDefinitionSysId: "seismicComponentId" // or null if not
    isInput: true/false, // whether to wait for a response value or if just output
    serializedControlData: "User defined JSON from generateControlData function";    
}