Configuring the portable Virtual Agent chat widget

  • Release version: Xanadu
  • Updated November 14, 2024
  • 2 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 Configuring the portable Virtual Agent chat widget

    The portable Virtual Agent chat widget enables ServiceNow customers to easily add Virtual Agent chat capabilities to third-party web pages, Service Portal, or UI Builder portals. This new Seismic component simplifies configuration and enhances user experience by supporting easier single sign-on (SSO) authentication and seamless integration with the Service Portal Agent Chat.

    Show full answer Show less

    Key Features

    • Easy Configuration: Simplifies the process of embedding Virtual Agent chat on various web portals.
    • Single Sign-On (SSO) Support: Supports a simpler SSO authentication flow when the instance and hosting site share the same external SSO provider.
    • System Parameters and Context Variables: Function identically to prior implementations, ensuring consistency.

    Prerequisites and Requirements

    • The widget uses an iframe element and requires the hosting third-party website to share the same parent domain as the ServiceNow instance (e.g., site1.company.com and site2.company.com).
    • If embedding on a subdomain without a shared parent domain, a custom instance URL must be used to avoid browser security issues.
    • Activate the com.snc.customurl plugin and add your purchased custom URL to your instance before embedding.

    Using SSO Authentication

    • SSO can be triggered from the chat widget if the instance uses an external SSO provider and the hosting site uses the same provider.
    • SSO integration requires creating a JavaScript script to handle authentication conditions and redirect users to a specified chat widget page.
    • Allowed redirect URLs must be specified in the com.glide.cs.webclientloginredirecturls system property.
    • Security system properties com.glide.cs.embed.cspframeancestors and com.glide.cs.embed.xframeoptions (for IE11) must be configured to define browser embedding policies and prevent clickjacking.

    Additional Notes

    • The Content Management System (CMS) application does not support Virtual Agent interfaces.
    • A legacy method exists to embed the chat widget using an iframe with optional automatic SSO for guest users.

    Practical Application

    ServiceNow customers can leverage the portable Virtual Agent chat widget to extend Virtual Agent chat functionality beyond the ServiceNow platform onto external web pages securely and with streamlined authentication. Proper domain configuration, enabling necessary plugins, and setting security policies ensure a secure and consistent chat experience across different environments.

    The portable chat widget can run on third-party web pages, in the service portal, or in UI Builder portals.

    The portable chat widget is a new Seismic component that makes it easy to add Virtual Agent chat to your page. It simplifies configuration and provides the following features:
    • Easily configurable
    • Simpler single sign-on (SSO) authentication flow
    • Connect to Service Portal Agent Chat
    • System parameters and context variables work the same as before

    Prerequisites for using the Portable Virtual Agent chat widget

    The Portable chat widget uses an inline frame element (iframe). The third-party website must be under the same parent domain as your ServiceNow® instance. For example, site1.company.com and site2.company.com share the same parent domain. If you're embedding the chat widget on any subdomain that is not shared with your ServiceNow instance, the URL must be a custom instance URL. Due to increased browser security, the chat widget may fail to load if you don't use a custom URL.

    Before you begin, do the following:
    1. Activate the custom URL plugin (com.snc.customurl) in your instance.
    2. Add the custom URL (that you previously purchased and registered) to your instance.
    Note:
    To learn more about using custom URLs, see Associating custom URLs to your instance.

    Using SSO authentication with the Portable Virtual Agent chat widget

    After you embed the Virtual Agent client, you can optionally trigger SSO authentication from the chat widget, but only when your instance is set up to use an external SSO provider. Your hosting site must also use the same SSO provider as your instance. For details on setting SSO providers, see External single sign-on (SSO).

    To trigger SSO authentication, create a JavaScript script that defines conditions for running authentication and redirects users to a chat widget page that you specify. You also specify the allowed URLs that can be passed in this script, by identifying them in the com.glide.cs.web_client_login_redirect_urls system property. Specify the full redirect URLs or the host part of the URL, such as https://example.com.

    This procedure requires that you set values for the following two system properties:
    • com.glide.cs.embed.csp_frame_ancestors
    • com.glide.cs.embed.xframe_options (IE 11 only)
    These properties determine the security policy for the embedded chat widget, namely how browsers render and secure HTML content for Virtual Agent and Live Agent chat, in an iframe, before you embed the web chat client. The HTTP header directives that you specify tell the browser whether a page can be embedded on certain domains to mitigate clickjacking attempts. Setting both properties ensures that there are security directives for major browsers and also older browsers, such as Internet Explorer.
    Note:
    If you're using the Content Management System (CMS) application to create custom interfaces for the ServiceNow AI Platform and ServiceNow® applications, be aware that it does not support Virtual Agent.