{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":42466,"path":"platform-user-interface/service-portal/configure-va-in-sp.md","title":"Configure Agent Chat in a portal","bundle":null,"doc_type":null,"release":"australia","body":"\n# Configure Agent Chat in a portal\n\nYour 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.\n\n## Before you begin\n\nRole required: admin\n\n-   Activate the Glide Virtual Agent \\(com.glide.cs.chatbot\\) or the Agent Chat \\(com.glide.interaction.awa\\) plugin. The Glide Virtual Agent plugin requires a subscription.\n\n    **Note:** For information about using Now Assist in Virtual Agent in portals, see [Configuring assistants overview](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/conversational-interfaces/configure-now-assist-va.md).\n\n\n## Procedure\n\n1.  Navigate to **All** &gt; **Service Portal** &gt; **Agent Chat**.\n\n    The Service Portal Agent Chat Configurations \\[sp\\_agent\\_chat\\_config\\] table opens.\n\n2.  Select **New**.\n\n3.  Complete the form.\n\n<table id=\"table_g4z_ldq_zgb\"><thead><tr><th>\n\nField\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nActive\n\n</td><td>\n\nWhether the configuration is active.\n\n</td></tr><tr><td>\n\nName\n\n</td><td>\n\nUnique name for the configuration record.\n\n</td></tr><tr><td>\n\nPortals\n\n</td><td>\n\nPortals to use with the specified chat configuration. If no portal is selected, the configuration applies to all portals in the system.\n\n</td></tr><tr><td>\n\nApplication\n\n</td><td>\n\nRead-only application scope for the record.\n\n</td></tr><tr><td>\n\nPublic\n\n</td><td>\n\nWhether Agent Chat is available to users before they log in.\n\n</td></tr><tr><td>\n\nRoles\n\n</td><td>\n\nRoles a user must have to use Agent Chat. If you don't select a role, Agent Chat is available to all users.\n\n</td></tr><tr><td>\n\nOrder\n\n</td><td>\n\nNumber indicating the order that configurations should run. Only one configuration applies per portal. If multiple configurations exist on a portal, the system runs the first configuration found from lowest to highest.\n\n</td></tr><tr><td>\n\nServer script\n\n</td><td>\n\nScript that passes page and widget data to an Agent Chat conversation. For example, pass a field to enable Agent Chat to access the value. Data passed in this script is available to every page in the portal. This script has access to the GlideSPScriptable API.\n\n **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.\n\n This example returns an object containing the list of catalogs associated with the portal.\n\n ```\n(function ($sp) {    \n   return {        \n      catalogs: $sp.getValue(‘catalogs’) \n   };\n})($sp);\n```\n\n 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.\n\n</td></tr></tbody>\n</table>4.  Select **Submit**.\n\n\n## Result\n\nUsers can initiate and maintain an Agent Chat conversation from any page in the selected portal.\n\n**Parent Topic:**[Create a portal](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/platform-user-interface/service-portal/create-a-portal.md)\n\n## Customize the Agent Chat button\n\nYou can change the color and images that are used in the Agent Chat button in your portal.\n\n### Before you begin\n\nIf 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://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/platform-user-interface/c_StoringImagesInTheDatabase.md).\n\nRole required: sp\\_admin or admin\n\n### About this task\n\nYou can configure the following elements of the Agent Chat button:\n\n-   The image to indicate that the chat window is open\n-   The image to indicate that the chat window is closed\n-   The button background color\n\nThese 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://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/conversational-interfaces/ac-configure-chat-branding.md).\n\n**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 `true`, set the web client Virtual Agent chat button to the same size as the original button icon, otherwise the icon is displayed oversize.\n\n### Procedure\n\n1.  Navigate to **All** &gt; **Service Portal** &gt; **Themes**.\n\n2.  Open a theme record.\n\n3.  In the **CSS variables** field, add the following variables:\n\n<table id=\"table_sqr_fcd_qkb\"><thead><tr><th>\n\nVariable\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\n`$sp-agent-chat-btn-close`\n\n</td><td>\n\nImage to indicate that the chat window is closed. Use an image URL that contains:-   Your instance address\n-   The name of the Image \\[db\\_image\\] record to reference\nFor example, to reference the `tack-icon.png` image in the database, enter the following:```\n$sp-agent-chat-btn-close: url(\"https://<instance-name>.service-now.com/tack-icon.png\");\n```\n\n \\[Omitted image \"sp-chat-close.png\"\\] Alt text: The image URL references tack-icon.png in the Agent Chat button\n\nTo use the default image, remove the variable.\n\n</td></tr><tr><td>\n\n`$sp-agent-chat-btn-open`\n\n</td><td>\n\nImage to indicate that the chat window is open. Use an image URL that contains:-   Your instance address\n-   The name of the Image \\[db\\_image\\] record to reference\nFor example, to reference the `book-icon.png` image in the database, enter the following:```\n$sp-agent-chat-btn-open: url(\"https://<instance-name>.service-now.com/book-icon.png\");\n```\n\n \\[Omitted image \"sp-chat-open.png\"\\] Alt text: The image URL references book-icon.png in the Agent Chat button\n\nTo use the default image, remove the variable.\n\n</td></tr><tr><td>\n\n`$sp-agent-chat-bg`\n\n</td><td>\n\nButton background color. Use a Hex code to set the color. For example, to use red, enter the following:```\n$sp-agent-chat-bg: #ff0000;\n```\n\n \\[Omitted image \"red-chat-icon.png\"\\] Alt text: Red background color\n\nTo use the default background color, remove the variable.\n\n</td></tr></tbody>\n</table>4.  Click **Update**.\n\n\n## Migrate from the Virtual Agent Service Portal widget\n\nIf 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.\n\n### Before you begin\n\nRole required: \\(admin or none\\)\n\n### Procedure\n\n1.  Record instance options and delete instances of the Virtual Agent Service Portal widget.\n\n    1.  Locate each instance of the Virtual Agent Service Portal widget and open the instance options.\n\n    2.  Record the values.\n\n    3.  Delete the widget instance.\n\n2.  If your widget instance included a color instance option, add the color variable to the portal theme record.\n\n    1.  Navigate to **Service Portal** &gt; **Themes**.\n\n    2.  Open the theme record for the portal.\n\n    3.  In the **CSS variables** field, add the `$sp-agent-chat-bg` variable and set the value to the desired color.\n\n        ```\n        $sp-agent-chat-bg: #ff0000\n        ```\n\n3.  If your widget instance options included URL parameters, add them to the Service Portal Agent Chat Configurations form **Server script** field.\n\n    **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.\n\n    1.  Navigate to the record in the Service Portal Agent Chat Configurations \\[sp\\_agent\\_chat\\_config\\] table for the desired portal.\n\n    2.  In the **Server script** field, write a custom script to pass the parameters to Agent Chat.\n\n        This example returns the value of the chat\\_queue field to the current conversation.\n\n        ```\n        (function ($sp) {    \n        \treturn {        \n        \t\tchat_queue: $sp.getValue('chat_queue')    \n        \t};\n        })($sp);\n        ```\n\n\n### Result\n\nWidget instances are removed from individual portal pages. Instead, the portal applies the Service Portal Agent Chat Configurations record to every portal page.\n\n## Pass page data to Agent Chat\n\nUse 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.\n\n### Before you begin\n\nRole required: admin\n\nExamine 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](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/conversational-interfaces/virtual-agent-scripts.md).\n\n### Procedure\n\n1.  Open the widget in the widget editor.\n\n2.  Update the widget client script.\n\n    1.  Inject the spContextManager service into the widget client script function.\n\n    2.  Pass variables to Agent Chat using the spContextManager API.\n\n    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.\n\n    ```\n    function ($scope, spContextManager) {\n    \n       spContextManager.addContext('agent-chat', {\n          'approval_count': 5       \n       });\n    };\n    ```\n\n    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.\n\n3.  Click **Save.**\n\n4.  Use Service Portal data in a Virtual Agent topic.\n\n    1.  Navigate to **Virtual Agent** &gt; **Designer** and open the topic in which you would like to use Service Portal data.\n\n    2.  Click **Edit Topic Flow**.\n\n    3.  Configure the topic as needed.\n\n        In a script field, use the `vaContext` object to access the context variable passed from the Service Portal.\n\n        For more information about creating a Virtual Agent topic, see [Create a Virtual Agent topic](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/conversational-interfaces/create-virtual-agent-topic.md).\n\n        For example, this script accesses the value of the `approval_count` variable in the Approvals widget.\n\n        ```\n        (function execute() {\n            return \"Your approval count is: \" + vaContext.approval_count;\n        })()\n        \n        ```\n\n    4.  Save and publish the topic.\n\n\n### Result\n\nAgent Chat can access the variables when an end user initiates a conversation from the Service Portal page.\n\n\\[Omitted image \"agent-chat-client.png\"\\] Alt text: Agent Chat displays the value of the variable.\n\n## Remove Live Chat link from the header menu\n\nIf your portal includes a Live Chat link in the header menu, you can remove it by updating the widget's option schema.\n\n### Before you begin\n\nRole required: admin\n\n### About this task\n\nAdding 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.\n\n### Procedure\n\n1.  In the Service Portal configuration page, navigate to **Portal Tables** &gt; **Instance with Menu**.\n\n2.  Open the record for your portal's header menu.\n\n    For example, open **SP Header Menu** if using the base system portal.\n\n3.  In the **Additional options, JSON format** field, add the following JSON key-value pair.\n\n    ```\n    “enable_live_chat”: {\n        “displayValue”: “false”,\n        “value”: false\n    }\n    ```\n\n    The final JSON looks like this.\n\n    ```\n    {\n        “enable_cart”: {\n            “displayValue”: “true”,\n            “value”: true\n        },\n         “enable_wishlist”: {\n           “displayValue”: “true”,\n             “value”: true\n         },\n        “enable_live_chat”: {\n          “displayValue”: “false”,\n            “value”: false\n        }\n    }\n    ```\n\n4.  Click **Update**.\n\n\n### Result\n\nWhen you navigate to the portal, **Live Chat** does not appear in the header menu.\n\n"}}