Thank you for your feedback.
Form temporarily unavailable. Please try again or contact docfeedback@servicenow.com to submit your comments.

Configure Agent Chat in Service Portal

Log in to subscribe to topics and get notified when content changes.

Configure Agent Chat in Service Portal

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.

Procedure

  1. Navigate to Service Portal > Agent Chat.
    The Service Portal Agent Chat Configurations [sp_agent_chat_config] table opens.
  2. Click New.
  3. Complete the form.
    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.

  4. Click Submit.

Result

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

Migrate from the Virtual Agent Service Portal widget

If 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.

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.
  2. If your widget instance included a color instance option, add the color variable to the portal theme record.
    1. Navigate to Service Portal > Themes.
    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
  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);

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

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.

    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 Agent > Designer 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.
      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.

Result

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

Agent Chat displays the value of the variable.

Remove Live Chat link from the header menu

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 Tables > Instance 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.
Feedback