Virtual Agent URL parameters

  • Release version: Xanadu
  • Updated May 31, 2025
  • 1 minute to read

    • Virtual Agent provides various system parameters that admins can add to an instance URL to control how page content is rendered.

    Virtual Agent URL structure

    You can control the page rendered for an instance by adding URL parameters to the instance URL, which is https://<instancename>.service-now.com.

    System parameters for Virtual Agent chat widget

    The Virtual Agent chat widget is supported for use in portals or embedded in third-party pages. The following system parameters control the conversation content rendered in the Virtual Agent chat widget.
    Parameter Description Example
    sysparm_branding_key

    Applies a chat branding configuration to the web chat client.

    Value: branding key for the configuration
    • Apply the branding configuration to a destination page:https://<instance_name>.service-now.com/$sn-va-web-client-app.do?sysparm_branding_key=<branding_key>
    • Apply the branding configuration to an embedded chat widget: https://<instance_name>.service-now.com/$sn-va-web-client-app._embed.do?sysparm_branding_key=<branding_key>
    sysparm_default_topic Sets the default topic on launch via topic sys_ID. https://<instance_name>.service-now.com/$sn-va-web-client-app.do?sysparm_default_topic=<topic_sys_id>
    sysparm_domain_id Restricts the chat to the specified sys ID for a domain. https://<instance_name>.service-now.com/$sn-va-web-client-app.do?sysparm_domain_id=<domain_sys_id>
    sysparm_live_agent_only Takes user directly to a live agent, if available. https://<instance_name>.service-now.com/$sn-va-web-client-app._embed.do?sysparm_live_agent_only=true
    sysparm_load_active_only Loads the current active conversation.
    Values:
    • true: Loads only the active conversation
    • false: Doesn't load active conversations
    Note:
    If the sysparm_skip_load_history and sysparm_load_active_only parameters are both set to true, the existing sysparm_skip_load_history parameter takes precedence.
    		 https://<instance_name>.service-now.com/$sn-va-web-client-app.do?sysparm_load_active_only=true
    sysparm_search_text Sets the search text for the conversation. https://<instance_name>.service-now.com/$sn-va-web-client-app.do?sysparm_search_text=<search_text>

    For example, <search_text> is request&laptop.
    sysparm_skip_load_history Skips the previous message history and starts a new conversation.
    Values:
    • true: Doesn’t load message history
    • false: Loads message history
    Note:
    If the sysparm_skip_load_history parameter is set to false and the sysparm_load_active_only is set to true, the sysparm_load_active_only loads the current active conversation.
    		 https://<instance_name>.service-now.com/$sn-va-web-client-app.do?sysparm_skip_load_history=true
    sysparm_ preview_mode Displays the conversation in test mode. https://<instance_name>.service-now.com/$sn-va-web-client-app.do?sysparm_preview_mode=true
    sysparm_requester_session_language Specifies the requester's language for the conversation session when Dynamic Translation for Virtual Agent is installed and configured. https://<instance_name>.service-now.com/$sn-va-web-client-app.do?sysparm_requester_session_language=<two-letter language code>