Configure the portable Virtual Agent chat widget

Configure the portable Virtual Agent chat widget to run Virtual Agent on third-party web pages.

Before you begin

Note: For new customers onboarding from Vancouver onward, the chat widget is only accessible to authenticated users by default. To allow unauthenticated users to access the chat widget, you must enable the sn_va_web_client_app_embed page for public access. For more information, see Make UI pages public or private.

Role required: admin

About this task

ServiceNow only supports the portable Virtual Agent when the top-level domain and domain name match the site that is loading the chat widget. SSO is only supported through the service-now.com URL. Anything beyond that will require custom solution and implementation.

Procedure

1. Navigate to All, and then enter sys_properties.list in the filter.

2. In the System Properties [sys_properties] table, search for the com.glide.cs.embed.csp_frame_ancestors property by name.

3. Click the property name to open the form and specify the directive values.

1. Return to the System Properties [sys_properties] table to search for the com.glide.cs.embed.xframe_options property by name.

2. Click the property name to open the form and specify the directive values.

1. Configure CORS Rules for the REST API to give access across domains.

   This rule gives the web domain you specify the rights to call the API that gives it access to the chat widget on the web page without a security restraint. All domains must share a common parent domain. Also, you must create a new CORS Rule for each subdomain that you want to support.

   1. Navigate to All > System Web Services > REST > CORS Rules.

   2. Click New.

   3. On the form, fill in the fields.

4.  On the **HTTP Methods** tab, select **GET**.

    The portable chat widget will only receive requests.

5.  Click **Submit**.

6.  Repeat these steps if you want to add the portable chat widget to another subdomain on your website.

1. Create a JavaScript script that uses thewindow.postMessage() method (Web API) to define event conditions that trigger SSO authentication in a user interface page and returns users to a chat widget page that you specify.

   To redirect users to a chat widget page, use the following string: "https://<your-instance>.service-now.com/sn_va_web_client_login.do?sysparm_redirect_uri=’ + encodeURIComponent(<your-page>)

   Note: Before you run the script, use the com.glide.cs.web_client_login_redirect_urls system property to specify the URLs that can be passed in the script. The redirection works only when you specify one or more allowed URLs in the property value. Specify the full redirect URLs or the host part of the URL. For example: https://example.com .

   Example script

   <script>
       window.addEventListener("message", function(e) {
          // redirect to SSO login if the chat widget logs in but is logged in as a guest user(unauthenticated)
         if(e.data.type==="SESSION_CREATED" && e.data.authenticated === false)
           window.location.href = "https://<your-instance>.service-now.com/sn_va_web_client_login.do?sysparm_redirect_uri=<’ + encodeURIComponent(<your-page>);
   
         // redirect to SSO login if the ServiceNow platform logs out from underneath the chat widget
         if(e.data.type==="SESSION_LOGGED_OUT")
           window.location.href = "https://<your-instance>service-now.com/"https://<your-instance>service-now.com/sn_va_web_client_login.do?sysparm_redirect_uri=’ + encodeURIComponent(<your-page>);
       });
     </script>
   

   In this example, authentication is triggered in the specified instance when the SESSION_CREATED or SESSION_LOGGED_OUT events occur. After authentication (when the SSO credentials for users are accepted), users are redirected to the embedded chat widget page that you specified in sn_va-web_client_login.do?sysparm_redirect_uri=’ + encodeURIComponent(<your-page>), as long as you also specified the page URL in the com.glide.cs.web_client_login_redirect_urls property.

What to do next

Add the portable Virtual Agent chat widget to a third-party website.

Parent Topic:Use the portable chat widget to add Virtual Agent to your web page