{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":4784,"path":"conversational-interfaces/virtual-agent/add-portable-va-client-website.md","title":"Add the portable Virtual Agent chat widget to a third-party website","bundle":null,"doc_type":null,"release":"australia","body":"\n# Add the portable Virtual Agent chat widget to a third-party website\n\nTo use the portable chat widget for Virtual Agent on third-party web pages, add the necessary code to your web page.\n\n## Before you begin\n\n[Configure the portable Virtual Agent chat widget](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/conversational-interfaces/virtual-agent/configure-portable-va-web-client.md) before completing this topic's steps.\n\nFor more information, review the [How to embed Virtual Agent in an external site](https://www.servicenow.com/community/virtual-agent-nlu-articles/how-to-embed-virtual-agent-in-an-external-site-updated-for-tokyo/ta-p/2308092) article on the ServiceNow Community site.\n\n**Note:** Interactive view and the ability to move and drag the chat window are currently unavailable in embedded enhanced chat.\n\nRole required: virtual\\_agent\\_admin or admin\n\n## About this task\n\nBoth enhanced and standard chat code is included in this topic. Review the beginning of each step to confirm you're implementing the applicable chat experience's steps.\n\n## Procedure\n\n1.  Enhanced chat only: Verify that your enhanced chat assistant is linked to a portal in **Conversational Interfaces** &gt; **Assistant Designer** &gt; **\\[Assistant name\\]**.\n\n    You can link to either a placeholder portal or an applicable portal. The portal suffix, for example, `esc`, is required for the following step.\n\n2.  Enhanced chat only: Import and instantiate this script reference to the page header to create a ServiceNow chat instance on your external page header:\n\n    **Note:** In the script reference example, `site1.example.com` refers to the URL for your ServiceNow instance.\n\n    ```\n    <script type=\"module\" > \n         import {EnhancedChat} from \"https://site1.example.com/uxasset/externals/embedded-enhanced-chat/index.jsdbx?sysparm_substitute=false\"; \n         var chat = new EnhancedChat ({ instance: https://site1.example.com, portal:<portal-suffix> }); \n       </script> \n    ```\n\n    **Tip:** If your organization uses a custom domain name, input the custom domain name as the instance property, rather than the ServiceNow domain name, to verify that browser results are consistent among multiple browsers.\n\n    -   **JSON configuration schema**\n\n        ```\n        instance: <string> - required. Origin of your ServiceNow instance, e.g.\n            'https://yourco.service-now.com'.\n        portal: <string> - required. ServiceNow portal suffix (e.g. 'esc', 'sp', or a\n            custom portal's suffix). Sent as the embed URL's `portal_suffix` param.\n        manageNowLogin: <boolean> - default false. When true, listens for the iframe's\n            SESSION_CREATED (unauthenticated) and SESSION_LOGGED_OUT postMessages and\n            redirects the *host page* to the instance's SSO login when either fires.\n        showSupportAndSettingsMenu: <boolean> - default false. Shows the chat's built-in\n            support/settings menu.\n        context: <object> - flat map of sysparm-style query params appended as-is to the\n            embed URL, e.g. { skip_load_history: 1, sysparm_debug: true }. Keys/values are\n            not validated or transformed - sent through with String(value).\n        pinnable: <boolean> - default true. Shows/hides the header's pin button, which\n            docks the panel full-height along the screen edge (position: 'pinned').\n        expandable: <boolean> - default true. Shows/hides the header's expand button,\n            which blows the panel up into a centered modal (position: 'modal').\n        position: <'modal' | 'pinned' | undefined> - initial docking state of the panel.\n            Leave undefined for the default floating panel. Also changes at runtime when a\n            visitor clicks the pin/expand buttons (see Events, below) - this is docking\n            state, not which side of the screen the launcher sits on (there's currently no\n            config for that; the launcher is fixed bottom-right).\n        container: <HTMLElement> - default document.body. Where the widget's root element\n            is appended.\n        title: <string> - default 'Now Assist'. Header title text and the iframe's\n            accessible title.\n        \n        unread: <object> - unread-message badge and proactive nudges. See \"Unread\n            messages and proactive nudges\" below for what this does and its limits.\n            enabled: <boolean> - default true. Set false to disable all of it.\n            notificationSoundUrl: <string> - URL of a chime played when a new unread\n                message arrives. No sound plays if omitted; there's no bundled default.\n        \n        branding: <object> - colors accept any valid CSS color value (hex, rgb(), a named\n            color, etc), not just rgb tuples or hex codes. Grouped by which part of the\n            widget each field paints, so it's always explicit whether a color applies to\n            just the launcher button, just the chat panel, just its header, or both.\n            launcher: <object> - the always-visible floating button that opens/closes\n                the panel.\n                bgColor: <string> - background color, default state (default: a\n                    green-to-blue gradient; set this to any solid color to replace it).\n                bgColorHover: <string> - background color on hover. The button also\n                    scales up slightly on hover (not configurable).\n                bgColorActive: <string> - background color while pressed/active.\n                color: <string> - icon color, default state.\n                colorHover: <string> - icon color on hover.\n                colorActive: <string> - icon color while pressed/active.\n                openIcon: <string> - URL of a custom icon for the closed state (default: a sparkle).\n                sizeMultiplier: <number> - scales the button and its icon uniformly\n                    (default is a 60px button with a 24px icon).\n            panel: <object> - the chat panel/window itself, not including its header.\n                bgColor: <string> - background color.\n                border: <string> - full CSS `border` shorthand, e.g. '1px solid #d1d5db'.\n                    Whole-property override, not separate color/width/style fields.\n                shadow: <string> - full CSS `box-shadow` value, e.g.\n                    '0 4px 12px rgba(0,0,0,0.2)'.\n            header: <object> - the header bar inside the panel (title, and its\n                expand/pin/close buttons).\n                iconColor: <string> - title icon color.\n                titleIcon: <string> - URL of a custom title icon (default: a sparkle).\n                buttonColor: <string> - expand/pin/close buttons' icon color, default\n                    state.\n                buttonColorActive: <string> - buttons' icon color while aria-pressed\n                    (i.e. the expand button when position is 'modal', or the pin\n                    button when position is 'pinned').\n                buttonBgColorHover: <string> - buttons' background on hover.\n                buttonBgColorActive: <string> - buttons' background while aria-pressed.\n                expandIcon: <string> - URL of a custom icon for the expand button,\n                    default state.\n                collapseIcon: <string> - URL of a custom icon for the expand button,\n                    expanded (position: 'modal') state.\n                pinIcon: <string> - URL of a custom icon for the pin button, default\n                    state.\n                pinnedIcon: <string> - URL of a custom icon for the pin button, pinned\n                    (position: 'pinned') state.\n            closeIcon: <string> - URL of a custom icon shared by the launcher's open\n                state and the header's close button (both mean \"close this widget\").\n            focusRing: <string> - full CSS `box-shadow` value for the focus-visible ring,\n                shared by both the launcher and header buttons.\n        \n        offsetX: <number> - default 25. Distance in pixels the widget is offset from its\n            default right edge.\n        offsetY: <number> - default 25. Distance in pixels the widget is offset from its\n            default bottom edge.\n        \n        zIndex: <number> - default 1000. Stacking order of the widget while not in modal\n            position.\n        modalZIndex: <number> - default 4000. Stacking order while position is 'modal'.\n        modalWidth: <string> - default '95vw'. Any valid CSS size (e.g. '900px', '80%').\n        modalHeight: <string> - default '85vh'. Any valid CSS size.\n        \n        translations: <object> - overrides for the widget's built-in English aria-labels.\n            Every button in the widget is icon-only, so these are its accessible names, not\n            visible tooltip text.\n            openLabel: <string> - launcher, closed state. Default 'Open chat'.\n            closeLabel: <string> - launcher opened state, and the header's close button.\n                Default 'Close chat'.\n            pinLabel: <string> - header's pin button, default state. Default 'Pin'.\n            unpinLabel: <string> - header's pin button, pinned state. Default 'Unpin'.\n            expandLabel: <string> - header's expand button, default state. Default\n                'Expand'.\n            contractLabel: <string> - header's expand button, expanded state. Default\n                'Contract'.\n        ```\n\n3.  Standard chat only:Import and instantiate this script reference to the page header to create a ServiceNow chat instance on your external page header:\n\n    **Note:** In the script reference example, `site1.example.com` refers to the URL for your ServiceNow instance.\n\n    ```\n    <script type=\"module\" >\n          import ServiceNowChat from \"https://site1.example.com/uxasset/externals/now-requestor-chat-popover-app/index.jsdbx?sysparm_substitute=false\";\n          var chat = new ServiceNowChat({ instance: \"https://site1.example.com/\", });\n        </script>\n    ```\n\n    **Tip:** If your organization uses a custom domain name, input the custom domain name as the instance property, rather than the ServiceNow domain name, to verify that browser results are consistent among multiple browsers.\n\n    -   **Example with configuration**\n\n        ```\n        const chat = new ServiceNowChat({\n        \tinstance: 'https://site1.example.com',\n        \tcontext: {\n        \t\tskip_load_history: 1\n        \t},\n        \tbranding: {\n        \t\tbgColor: '#333',\n        \t\tprimaryColor: '#000',\n        \t\thoverColor: '#EFEFEF',\n        \t\tactiveColor: '#AAA',\n        \t\topenIcon: 'custom-open.svg',\n        \t\tcloseIcon: 'custom-close.svg',\n        \t\tsizeMultiplier: 1.6\n        \t},\n        \toffsetX: 50,\n        \toffsetY: 50,\n        \tposition: 'left',\n        \ttranslations: {\n        \t\t'Open dialog': 'Open chat',\n        \t\t'Open Chat. {0} unread message(s)': 'Click to open',\n        \t\t'Close chat.': 'Click to close',\n        \t},\n        });\n        ```\n\n    -   **JSON configuration schema**\n\n        ```\n        {\n            instance: <string> - url to your instance, must be of the same domain (sub-domain)\n            context: <object> - sys_parm variables to pass into the iframe\n            branding: <object> - branding settings\n                  bgColor: <rgb|hex> - can take an rgb tuple, ie: '56,56,56' or a 3 or 6 hex color code, ie: #333 or #efefef.  background color of button\n           \tprimaryColor: <rgb|hex> - font color\n           \thoverColor: <rgb|hex> - hover background color of button\n           \tactiveColor: <rgb|hex> - click / active background color of button\n           \topenIcon: <string> - name of the uploaded custom icon in settings\n           \tcloseIcon: <string> - name of the uploaded custom icon in settings\n           offsetX: <integer> - distance in pixels the button moves along the x-axis\n           offsetY: <integer> - distance in pixels the button moves along the y-axis\n           position: <enum: left|right> - position left or right side of screen\n           translations: <object> - contains label mappings for translations or label changes\n           \t'Open dialog': <string> - replacement text for accessibility\n           \t'Open Chat. {0} unread messages(s)': <string> - replacement text for tooltip\n           \t'Close chat.': <string> - replacement text for tooltip\n        }\n        ```\n\n\n**Parent Topic:**[Use the portable chat widget to add Virtual Agent to your web page](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/conversational-interfaces/virtual-agent/use-portable-va-web-client.md)\n\n"}}