Develop a component for Virtual Agent

  • Release version: Yokohama
  • Updated January 30, 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 Develop a component for Virtual Agent

    This guide explains how ServiceNow customers can create custom components for Virtual Agent to either display information or gather user input within the Virtual Agent client interface. Custom components extend Virtual Agent capabilities by enabling tailored user interactions beyond standard controls.

    Show full answer Show less

    Types of Virtual Agent Components

    • Response Components: These components display information only, without user interaction. They require a controlData property to receive initial data from the server.
    • Input Components: These components both display information and collect user input. They include controlData for initial data, responseValue to capture user input, and a forceCloseControl flag to control whether the component is interactive or closed.

    Key Properties and Actions

    Response components use controlData (a JSON object) to receive data as the Virtual Agent topic runs.

    Input components use:

    • controlData: Initial data from the server.
    • responseValue: Data capturing the user's response.
    • forceCloseControl: Boolean flag indicating if the component is closed to input.

    Input components emit the VACONTROL#VALUESENT action to send user input back to the server.

    Input Component States and Interaction Flow

    • Waiting for Input: Component is active and ready for user input. The user interacts with the control (e.g., slider), and confirms input (e.g., clicks a button) to send data.
    • Handling Input: User action triggers an event that updates state to close the component and dispatches the input data to the server.
    • Closed: The component no longer accepts input, either because the user responded or the conversation proceeded. The component re-renders showing the user’s submitted response.

    Adding Custom Components to Virtual Agent Designer

    After developing and deploying the component to your instance, you can add it to Virtual Agent Designer as a custom control with appropriate definitions and properties to enable communication with the Virtual Agent interface.

    Testing

    It is important to test your Virtual Agent custom component in your instance before deploying it broadly to ensure it behaves as expected within conversations.

    Create a custom Virtual Agent component to gather input or display information in the Virtual Agent client interface.

    Types of Virtual Agent components

    To develop a component for Virtual Agent, add specific properties and actions to interact with the Virtual Agent client interface. The properties required depend on the type of component you are creating.

    Response component

    A response component only provides information to the user, and does not gather input or handle user interaction. For example, a card control that does not require user input and is only in the conversation once.A card control as an output component that does not require user input

    Add a property to your response component to handle the data sent by the Virtual Agent server.

    Table 1. Output component properties
    Property Description
    controlData Initial data that the Virtual Agent server sends to your component as the topic runs.

    Data type: JSON Object
    Input component

    An input component displays information and/or gathers user input. It includes the same property as the output component to handle data sent by the server, but has more possible states and requires user interaction.

    Table 2. Input component properties
    Property Description
    controlData Initial data that the Virtual Agent server sends to your component as the topic runs.

    Data type: JSON Object
    responseValue Data sent to the component from the user's response, either from the client directly, or from the server if there is a refresh. Only use in components that require user input.

    Data type: JSON Object
    forceCloseControl Flag that indicates whether the component can accept input. When true, the control closes and the user cannot interact with it. Monitor changes on the client to update this value. Only use in components that require user input.

    Data type: Boolean

    Use this action to emit data from user interaction.

    Table 3. Input component actions
    Action Description
    VA_CONTROL#VALUE_SENT Response data from the client to send to the server. Only use in components that require user input.

    Data type: JSON Object

    Input component states

    Because they accept data, input components must handle multiple states. The state flow is generally as follows:

    1. Virtual Agent shows the custom component in the waiting for input state.
    2. The user interacts with the component to provide input.
    3. The component closes and sends the responseValue property to the server.
    4. The server runs the server-side logic and sends the component with the user's input back to the client.
    Waiting for Input

    The initial state of a component waiting for user interaction. The controlData property is set, but the forceControlClosed property is false. This example shows a slider component in the waiting for input state.

    Component waiting for input.

    In this example, if the user has not provided a responseValue and the control is not closed, the slider and the input button display.

    const {controlClosed, sliderVal, sliderMin, sliderMax} = state;
return (<div class={{"slider-chat": true}}>
    {responseValue ? null :  <Fragment>
    <div class={{"slider-label": true}}>{label}</div>
    {controlClosed ? null : <Fragment>
        <div class={{"slider-container": true}}>
                    <input on-change={onSliderChange} type="range" min={sliderMin} max={sliderMax} value={sliderVal} class={{"slider": true}} />
            <div class={{"slider-value": true}}>
                    {unitIcon && 
                     <div class={{"unit-icon": true}}><img src={unitIcon} /></div>
                     } 
                     {sliderVal} {unitName}
                </div>
        <div class={{"button-container":true}}>
            <now-button variant="primary" label={buttonText || 'Confirm'} />
         </div></div></Fragment>}
    Handling Input

    In the previous example, the slider uses a now-button component, which the user clicks to confirm input and send it to the server. When the user clicks the button, the VA_CONTROL#VALUE_SENT action fires with the responseValue payload.

    'NOW_BUTTON#CLICKED': (data) => {
    const {updateState, dispatch, state: {sliderVal}} = data;
    updateState({controlClosed: true});
    dispatch('VA_CONTROL#VALUE_SENT', {
        value: {
            sliderVal
        }
    }); 
}
    Closed

    A component that is closed can no longer accept user input. Components are generally closed because:

    • The user responded to the component. The component closes and the conversation continues.
    • The user ended the chat. The server does not wait for a response.

    For example, the slider component only renders the original prompt when in the closed state.

    Closed component that is no longer waiting on user input.

    Sending response

    After the user responds, the control is rendered again on the user's side of the conversation with the value of the responseValue property.

    Users response sent to the client.

    For example, the slider control uses this snippet to render the response.

    {responseValue && <div className="response-container slider-value">
   {unitIcon && 
   <div className="unit-icon"><img src={unitIcon} /></div>
   } 
   {returnVal} {unitName}
</div>}

    Adding the component to Virtual Agent Designer

    After developing the component and deploying it to your instance, add it to Virtual Agent Designer using a custom control and definition. For more information, see Virtual Agent custom controls.