---
sourceDocument: Zurich ServiceNow AI Platform user interface
sourceDocumentLink: https://www.servicenow.com/docs/r/zurich/platform-user-interface

 Release :

    - zurich

ft:locale :

    - en-US

ft:publication_title :

    - Zurich ServiceNow AI Platform user interface

ft:clusterId :

    - platux

bundleId :

    - platux

workflow :

    - Platform


---

# Configure Agent Chat in a portal

# Configure Agent Chat in a portal {#ariaid-title1}

* Release version: Zurich
* 
* Updated July 31, 2025
* 
* ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 7 minutes to read

Your end users can initiate and maintain an Agent Chat conversation in any portal page. Write a script to pass portal-specific data to Agent Chat. For example, pass the name of your knowledge base to a Virtual Agent conversation.

## Before you begin

Role required: admin

* Activate the Glide Virtual Agent (com.glide.cs.chatbot) or the Agent Chat (com.glide.interaction.awa) plugin. You can activate the Glide Virtual Agent plugin only if you have a subscription.  
  Note:  
  For information about using Now Assist in Virtual Agent in portals, see [Configuring assistants overview](https://www.servicenow.com/docs/access?context=configure-now-assist-va&version=zurich&pubname=zurich-conversational-interfaces&ft:locale=en-US).
{#configure-va-in-sp__ul_mng_b5t_dhb}

## Procedure

1. Navigate to AllService PortalAgent Chat.  
   The Service Portal Agent Chat Configurations \[sp_agent_chat_config\] table opens.
2. Select New.
3. Complete the form.  
   {#configure-va-in-sp__table_g4z_ldq_zgb__entry__2}

   | Field | Description |
   |-|-|
   | Active | Select to make the configuration active. |
   | Name | Enter a unique name for the configuration record. |
   | Portals | Select the portals in which you would like to use the specified chat configuration. If no portal is selected, the configuration applies to all portals in the system. |
   | Application | Read-only application scope for the record. |
   | Public | Select to make Agent Chat available to users before they log in. |
   | Roles | Select the roles a user must have to use Agent Chat. If you don't select a role, Agent Chat is available to all users regardless of their role. |
   | Order | Enter a number indicating the order that the configurations should run. Only one configuration applies per portal. If there are multiple configurations on a portal, the system runs the first configuration found from lowest to highest. |
   | Server script | Write a script that passes page and widget data to an Agent Chat conversation when a user initiates the conversation. For example, pass a field to the chat conversation to enable Agent Chat to access the value. Data passed in this script is available to every page in the portal associated with this record. This script has access to the GlideSPScriptable API. Note: The portal suffix, page ID, and language are automatically available to Agent Chat and do not require a custom script. Sys ID and table are automatically available to Agent Chat when they are present in the URL. This example returns an object containing the list of catalogs associated with the portal to the current conversation. (function ($sp) { return { catalogs: $sp.getValue('catalogs') }; })($sp); When Agent Chat opens in an `iframe` HTML element, the list of catalogs is included in the `iframe` URL. Parameters from this field override any conflicting page data passed to Agent Chat. |
   [ ]

   {#configure-va-in-sp__table_g4z_ldq_zgb}
4. Select Submit.

## Result

Users can initiate and maintain an Agent Chat conversation from any page in the selected portal.

## Customize the Agent Chat button {#ariaid-title2}

You can change the color and images that are used in the Agent Chat
button in your portal.

### Before you begin

If you plan to replace one or both of the images that are used in the Agent Chat button, upload the images to your instance. For more
information on uploading an image, see [Storing images in the
database](https://www.servicenow.com/docs/Tna0Nquc_zuZLFYBEvAPNA "Administrators and users with the image_admin or content_admin role can upload and store images in the database. These images are saved in the Images [db_image] table. Uploading an image to the database allows it to be referenced from HTML fields by appending the name of the image to the URL of the instance.").

Role required: sp_admin or admin

### About this task

You can configure the following elements of the Agent Chat button:

* The image to indicate that the chat window is open
* The image to indicate that the chat window is closed
* The button background color
{#configure-va-icon__ul_ehw_b1b_wkb}

These elements are determined in the portal theme. To customize the Agent Chat button, update the relevant SCSS variables in the portal theme record. For more information, see [Set up your bot's branding](https://www.servicenow.com/docs/access?context=ac-configure-chat-branding&version=zurich&pubname=zurich-conversational-interfaces&ft:locale=en-US).  
Note:  
If you change the web client Virtual Agent button icon while the system property \[sys_property\] table value com.glide.cs.advanced-chat.popover is set to <kbd class="ph userinput">true</kbd>, set the web client Virtual Agent chat button to the same size as the original button icon, otherwise the icon is displayed oversize.

### Procedure

1. Navigate to AllService PortalThemes.
2. Open a theme record.
3. In the CSS variables field, add the following variables:  
   {#configure-va-icon__table_sqr_fcd_qkb__entry__2}

   | Variable | Description |
   |-|-|
   | `$sp-agent-chat-btn-close` | Image to indicate that the chat window is closed. Use an image URL that contains: * Your instance address * The name of the Image \[db_image\] record to reference {#configure-va-icon__ul_k4z_khb_wkb}For example, to reference the `tack-icon.png` image in the database, enter the following: $sp-agent-chat-btn-close: url("https://<instance-name>.service-now.com/tack-icon.png"); ![The image URL references tack-icon.png in the Agent Chat button]() To use the default image, remove the variable. |
   | `$sp-agent-chat-btn-open` | Image to indicate that the chat window is open. Use an image URL that contains: * Your instance address * The name of the Image \[db_image\] record to reference {#configure-va-icon__ul_jgn_nhb_wkb}For example, to reference the `book-icon.png` image in the database, enter the following: $sp-agent-chat-btn-open: url("https://<instance-name>.service-now.com/book-icon.png"); To use the default image, remove the variable. |
   | `$sp-agent-chat-bg` | Button background color. Use a Hex code to set the color. For example, to use red, enter the following: $sp-agent-chat-bg: #ff0000; ![Red background color]() To use the default background color, remove the variable. |
   [ ]

   {#configure-va-icon__table_sqr_fcd_qkb}
4. Click Update.

## Migrate from the Virtual Agent
Service Portal widget {#ariaid-title3}

If you are upgrading from a previous release, your portal implementation may include the Virtual Agent Service Portal widget. Migrate widget options to the Agent Chat in Service Portal configuration and remove all instances of the widget to enable your users to initiate and maintain an Agent Chat conversation in any portal page.

### Before you begin

Role required: (admin or none)

### Procedure

1. Record instance options and delete instances of the Virtual Agent Service Portal widget.
   1. Locate each instance of the Virtual Agent Service Portal widget and open the instance options.
   2. Record the values.
   3. Delete the widget instance.
   {#migrate-chat-to-va__substeps_qhr_35t_dhb}
2. If your widget instance included a color instance option, add the color variable to the portal theme record.
   1. Navigate to Service PortalThemes.
   2. Open the theme record for the portal.
   3. In the CSS variables field, add the `$sp-agent-chat-bg` variable and set the value to the desired color.  

          $sp-agent-chat-bg: #ff0000

   {#migrate-chat-to-va__substeps_ygq_y5t_dhb}
3. If your widget instance options included URL parameters, add them to the Service Portal Agent Chat Configurations form Server script field.  
   Note:  
   The portal suffix, page ID, and language are automatically available to Agent Chat and do not require a custom script. Sys ID and table are automatically available to Agent Chat when they are present in the URL.
   1. Navigate to the record in the Service Portal Agent Chat Configurations \[sp_agent_chat_config\] table for the desired portal.
   2. In the Server script field, write a custom script to pass the parameters to Agent Chat.  
      This example returns the value of the chat_queue field to the current
      conversation.

          (function ($sp) {    
          	return {        
          		chat_queue: $sp.getValue('chat_queue')    
          	};
          })($sp);

   {#migrate-chat-to-va__substeps_ss4_qvt_dhb}

### Result

Widget instances are removed from individual portal pages. Instead, the portal applies the Service Portal Agent Chat Configurations record to every portal page.

## Pass page data to Agent Chat {#ariaid-title4}

Use the spContextManager class in a widget client script to pass
dynamic page data to Agent Chat. For
example, pass the number of approvals in the Approvals widget to Agent Chat when a user initiates a
conversation from the Service Portal
homepage.

### Before you begin

Role required: admin

Examine the widget to understand how data is passed to the
widget client script. To make data available to Agent Chat, you must pass it
to the spContextManager service. You can then access the data in
a Virtual Agent topic using
the `vaContext` object. For more information about using context
variables in Virtual Agent
scripts, see Virtual Agent scripts.

### Procedure

1. Open the widget in the widget editor.
2. Update the widget client script.
   1. Inject the spContextManager service into the widget client script function.
   2. Pass variables to Agent Chat using the spContextManager API.

   {#dynamic-chat-config__substeps_hbq_43y_qhb}  
   This example passes `approval_count` to Agent Chat. When a
   user initiates a conversation from the Service Portal
   homepage, the system appends `&sysparm_approval_count=5`
   to the Agent Chat
   `iframe` URL.

       function ($scope, spContextManager) {

          spContextManager.addContext('agent-chat', {
             'approval_count': 5       
          });
       };

   Keys passed to this API are unique per page. For example, if the `'agent-chat'` key is already initialized by another widget on the page through the addContext() method, you must use the updateContextForKey() method to update the key's data. . For more information about the spContextManager
   class, see spContextManager.
3. Click Save.
4. Use Service Portal data in a Virtual Agent topic.
   1. Navigate to Virtual AgentDesigner and open the topic in which you would like to use Service Portal data.
   2. Click Edit Topic Flow.
   3. Configure the topic as needed.  
      In a script field, use the `vaContext` object to access the context variable passed from the Service Portal.

      For more information about creating a Virtual Agent topic, see [Create a Virtual Agent topic](https://www.servicenow.com/docs/access?context=create-virtual-agent-topic&version=zurich&pubname=zurich-conversational-interfaces&ft:locale=en-US).  
      For example, this script accesses the value of the `approval_count` variable in the Approvals widget.

          (function execute() {
              return "Your approval count is: " + vaContext.approval_count;
          })()

   4. Save and publish the topic.
   {#dynamic-chat-config__substeps_ukb_pcq_23b}

### Result

Agent Chat can access the variables when an end user initiates a conversation from the Service Portal page.

## Remove Live Chat link from the header menu {#ariaid-title5}

If your portal includes a Live Chat link in the header menu, you can remove it by
updating the widget's option schema.

### Before you begin

Role required: admin

### About this task

Adding the Chat Queue field to a portal record adds the Live
Chat link to the portal's header menu. If you integrate your portal with Agent Chat, the Live Chat link is no longer needed.

### Procedure

1. In the Service Portal configuration page, navigate to Portal TablesInstance with Menu.
2. Open the record for your portal's header menu.  
   For example, open SP Header Menu if using the base system portal.
3. In the Additional options, JSON format field, add the following JSON key-value pair.  

       "enable_live_chat": {
           "displayValue": "false",
           "value": false
       }

   The final JSON looks like this.

       {
           "enable_cart": {
               "displayValue": "true",
               "value": true
           },
            "enable_wishlist": {
              "displayValue": "true",
                "value": true
            },
           "enable_live_chat": {
             "displayValue": "false",
               "value": false
           }
       }

4. Click Update.

### Result

When you navigate to the portal, Live Chat does not appear in the header menu.

*[\>]: and then