Embedding the Employee Navigator chat panel in your website

As a website developer, you can embed the Employee Navigator chat panel in an HTML-based website. The panel is injected as an iframe by a script that connects to your BMC Helix Digital Workplace instance and loads the chat interface inside your website. However, the chat panel can't be embedded inside any page in BMC Helix Digital Workplace, the guest portal, or the external portal. 

You can configure the panel by specifying a BMC HelixGPT skill, setting a custom panel title, adjusting its appearance, or launching it from a custom button instead of the default floating icon.

End users can use this chat panel to get an intelligent, context-aware assistance without leaving the website. Alternatively, they can access the panel as a standalone web page by using the direct chat URL. To launch the panel as a standalone webpage, only the BMC HelixGPT skill must be selected for the Employee Navigator panel in the Admin Console. No other configurations are required. 

For more information about the benefits of using the embedded Employee Navigator chat panel and examples of user interaction, see Using Employee Navigator capabilities in your website.

Before you begin

Before embedding the Employee Navigator chat panel, ensure the following prerequisites are met:

• BMC HelixGPT entitlement: Your organization must be entitled to use BMC HelixGPT. For more information, see BMC Helix Service Management service.
• Employee Navigator skill configuration: As a BMC Helix Digital Workplace administrator, you must select a BMC HelixGPT skill for the Employee Navigator panel in the Admin Console. 
  This skill is used by default to provide AI capabilities in the embedded panel and when the panel is launched as a standalone web page. For more information, see Configuring BMC HelixGPT in the end-user console and studio pages. While Employee Navigator Supervisor is the recommended core skill, you can select other prompt-based or agentic skills depending on your use case.
• Alternative skill configuration: To use an alternative skill for the embedded Employee Navigator panel, you must locate an appropriate out-of-the-box skill or create a custom skill in BMC HelixGPT Admin Studio. You must then copy its Skill ID and reference it in the embed script to override the skill configured in the Admin Console. For instructions on creating and configuring skills, see Creating and managing skills. 
• Basic web development knowledge: You must have a foundational understanding of web development to embed and configure the chat panel.
• Content-Security-Policy (CSP) configuration: You must update your website’s CSP header to allow script-src and style-src directives for the BMC Helix Digital Workplace host.
  This configuration must be applied in the application your organization uses to serve and render the website. The exact steps depend on the technology stack used. For example, procedures for configuring CSP headers might be different for Nginx and Apache web servers. 
• Secure context requirement: The website where you embed the chat panel must be served over HTTPS, as embedding in non-secure (HTTP) contexts is not supported.

Process for embedding the Employee Navigator chat panel

The following table describes the actions that you must perform to embed the Employee Navigator chat panel in a website:

Task 1: To set the HTTP headers for the embeddable chat panel

To allow the Employee Navigator chat panel to be embedded in a website, configure the Content-Security-Policy headers:

1. Log in to BMC Helix Innovation Studio.
2. On the Workspace tab, select Digital Workplace > Records.
3. On the Records tab, select HttpResponseHeaders record and click Edit data.
4. On the Data Editor (HttpResponseHeaders) page, open a record associated with your BMC Helix Digital Workplace subtenant.
5. In the Value field, replace the default value of frame-ancestors 'none' with one of the following values:
   • A specific domain to allow embedding only from that site. For example, frame-ancestors https://example.org
   • Multiple domains to allow embedding from several sites. For example, frame-ancestors https://example.org https://acme.com
   • An asterisk (*) to allow embedding from any website. 
     
     WarningOnly update the frame-ancestors directive. Do not modify other parts of the header value.
     
     
      
6. Click Save.

Task 2: To register the website URL

Specify the trusted URL of the website in which you want to embed the chat panel: 

1. Log in to BMC Helix Innovation Studio and navigate to the Administration tab. 
2. Select Integrations > Iframe Security.
3. On the Iframe Security page, navigate to the Trusted websites section.
4. Enter the address of the website and click Add to list.
   For example, https://view.host.com.
   You can add multiple URLs.
   Warning

   Important

   Do not include any wildcard character, such as asterisk (*) in the URL.

5. Click Save.

Task 3: To configure BMC Helix SSO to open the Employee Navigator chat panel in an iframe

To open the Employee Navigator chat panel in an iframe, you have to configure the BMC Helix Single Sign-On server to allow opening it from domains other than the BMC Helix Single Sign-On server domain.

1. Log in to the BMC Helix SSO Admin Console.
2. To include all the external domains from which the chat panel can be opened in an iframe, complete the following steps:
   1. In the BMC Helix SSO Admin Console, select Realms tab, and then click Edit to view the realm configuration. 
   2. On the Authentication tab, configure the ALLOW-FROM Domain(s) setting to include all the external domains from which the chat panel can be opened in an iframe.
      For more information about how to configure this setting, see To configure BMC Helix SSO to open applications in iframes in Configuring BMC Helix SSO to open applications in iframes.
3. To set the cookie security options for the tenant of the BMC Helix SSO server used to authenticate the application, complete the following steps:
   1. In the BMC Helix SSO Admin Console, select General > Advanced.
   2. Set the following options:
      • Set the Secure Cookie setting to ON. 
      • Set the Same Site Cookie setting to None.
        For more information about setting cookie security, see To manage the cookie security for end users by setting site cookie properties in Configuring settings for the BMC Helix SSO server.

Task 4: To include the script in the website

To load the Employee Navigator chat panel, add a script tag to your website’s HTML file:

1. Open the website’s index.html file.
2. Add the following <script> tag before closing the <body> tag:
   <script defer src="<<dwp-server:port>>/app/navigator/script/navigator-trigger.min.js" type="text/javascript" id="dwp-navigator__trigger-script">
3. Replace <<dwp-server:port>> with the actual hostname of your BMC Helix Digital Workplace instance. For example: 
   <script defer src="https://dwp-org.bmc.com/app/navigator/script/navigator-trigger.min.js" type="text/javascript" id="dwp-navigator__trigger-script">
   Ensure the hostname is served over HTTPS. Embedding over HTTP is not supported due to cross-site cookie requirements.

After you add the script and reload the page, the panel is automatically injected in the page as an iframe. A floating icon appears on the website that users can click to open the panel. By default, the panel uses the following attributes:

• BMC HelixGPT skill that is selected in the Digital Workplace Admin Console
• Default panel title
• Default styling

(Optional) Task 5: To customize the skill and the panel label

You can configure the chat panel to use a custom BMC HelixGPT skill, set a custom panel title, localize the title, and modify the styling of the default floating icon.

To apply these customizations, add the following data-* attributes to the <script> tag:

The following example displays the customization of the panel title:

The following example shows how to adjust the panel title to different user languages:

(Optional) Task 6: To customize the icon and chat panel style

You can override the default appearance of the floating icon and the chat panel container by applying custom CSS.

1. Download the default stylesheet by using the following URL: https://<your-dwp-host>/dwp/navigator/script/navigator-variables.css
   Replace  <your-dwp-host> with the actual hostname of your BMC Helix Digital Workplace instance. 
2. Modify the CSS variables as required. 
   Refer to the full list of customizable variables in the stylesheet to adjust colors, sizes, positioning, shadows, and more.
3. Save the file locally or host it on your site.
4. Include the updated stylesheet in your index.html by adding the following <link> tag and specifying the path to the CSS file: <link rel="stylesheet" href="https://<<path-to-css-file>>" type="text/css">

Also, if your website defines global style variables, such as --primary-color, the chat panel can inherit them. For example, you can apply your site’s primary color to the floating icon:
--dwp-navigator-trigger-background: var(--primary-color)

--dwp-navigator-trigger-display

--dwp-navigator-trigger-background

--dwp-navigator-trigger-border

--dwp-navigator-trigger-border-radius

--dwp-navigator-trigger-color

--dwp-navigator-trigger-z-index

--dwp-navigator-trigger-initial-top

--dwp-navigator-trigger-initial-bottom

--dwp-navigator-trigger-initial-start

--dwp-navigator-trigger-initial-end

--dwp-navigator-trigger-width

--dwp-navigator-trigger-height

--dwp-navigator-trigger-transform

--dwp-navigator-trigger-box-shadow

--dwp-navigator-trigger-transition

--dwp-navigator-trigger-transform-hover

--dwp-navigator-trigger-box-shadow-hover

--dwp-navigator-trigger-outline-color

--dwp-navigator-iframe-z-index

--dwp-navigator-iframe-initial-top

--dwp-navigator-iframe-initial-bottom

--dwp-navigator-iframe-initial-start

--dwp-navigator-iframe-initial-end

--dwp-navigator-iframe-width

--dwp-navigator-iframe-height

--dwp-navigator-iframe-min-width

--dwp-navigator-iframe-border-radius

--dwp-navigator-iframe-background

--dwp-navigator-iframe-box-shadow

--dwp-navigator-iframe-transition

--dwp-navigator-title-background

--dwp-navigator-title-min-height

--dwp-navigator-title-padding

--dwp-navigator-title-font-size

--dwp-navigator-title-font-weight

--dwp-navigator-title-font-color

--dwp-navigator-title-button-width

--dwp-navigator-title-button-height

--dwp-navigator-title-button-border

--dwp-navigator-title-button-background

--dwp-navigator-title-button-color

--dwp-navigator-title-button-border-hover

--dwp-navigator-title-button-background-hover

--dwp-navigator-title-button-color-hover

--dwp-navigator-title-button-outline-color

(Optional) Task 7: To add a custom button

Instead of using the default floating icon, you can configure a custom button to launch the Employee Navigator chat panel. This setup allows for greater control over the button placement, styling, and behaviour. You can also add multiple custom buttons, each configured to open a chat panel powered by a different BMC HelixGPT skill, allowing you to tailor interactions based on specific use cases.

1. Update your Content Security Policy (CSP) header to include 'unsafe-inline' in the script-src directive.
   This setting is required to support inline scripts, which are necessary for enabling button event handlers such as onclick.

   Important

   The unsafe-inline keyword allows the use of inline code within HTML elements, such as event handlers. This behavior is typically restricted by strict CSP configurations due to potential security vulnerabilities. Use this setting only if necessary, and consider implementing additional security measures such as CSP nonces or hashes to mitigate risks. Inserting custom buttons requires this setting.

2. Insert a button in your HTML where you want users to trigger the chat panel:<button onclick="dwpNavigator.start({skillId: 'SkillID', productName: 'Chat panel title'}); dwpNavigator.show()">Button label</button>
   1. Use the dwpNavigator.start() function to define the chat panel’s behavior. You can pass the following parameters:

      Attribute	Type	Description
      skillId	String or null	Specify the ID of a BMC HelixGPT skill to use in the chat.
      productName	String or Object	Set the custom panel title and the accessibility labels of the different views.
      language	String	Set the title language. You can specify only the languages supported by BMC Helix Digital Workplace.  The conversation language inside the chat panel uses the user's language as determined by the chat server, and it might differ from the language of the panel's wrapper.
      custom	Boolean	Set this value to true to remove the default SVG styling of stars in the button.

   2. After calling the dwpNavigator.start() function, you must also call dwpNavigator.show() to open the panel in its new state.
3. (Optional) Style the button by using inline styles or CSS classes.
4. (Optional) Hide the default floating icon by setting the following CSS variable:
   --dwp-navigator-trigger-display: none;
   You can set this variable via inline styles or in your stylesheet.

Where to go from here

Using Employee Navigator capabilities in your website