Embedding BMC Helix Chatbot in external applications

The developer of an application that is not developed on the BMC Helix Platform can embed BMC Helix Chatbot UI in the application. End users can interact with BMC Helix Chatbot for self-service, access knowledge articles, or create service requests.

For information about the benefits of embedding the BMC Helix Chatbot UI and an example of how end users can interact with BMC Helix Chatbot, see Leveraging-BMC-Helix-Chatbot-UI-in-your-application.

Before you begin

If you want to add a custom icon, ensure that you convert the picture in its css code by using a base64 converter, such as base64-image.

Workflow for embedding BMC Helix Chatbot UI in an application

The following table describes the actions that an administrator and a developer must perform to embed the BMC Helix Chatbot UI:

Task	Role	Product	Action	Reference
1	Administrator	BMC Helix Innovation Studio	Register the application URL in which you want to embed the BMC Helix Chatbot UI.	To register the application URL
2	Application developer	index.html file of the application	Include the view-loader.js file from the BMC Helix Platform, add the BMC Helix Chatbot button, and register a function that returns a JWT token.	To include view-loader.js file in an application
3	Application developer	index.html file of the application	(Optional) Configure the BMC Helix Chatbot button properties such as icon, color, position, size, and margin.	To customize the embedded BMC Chatbot button

Task 1: To register the application URL

Specify the trusted URL of the application in which you want to embed the BMC Helix Chatbot UI.

Log in to BMC Helix Innovation Studio and navigate to the Administration tab.
Select Configure My Server > Helix Platform > Iframe Security.
On the iframe Security page, click Add URL, and enter the address of the server hosting the application.
For example, http://host.com, view.host.com:443, https://view.host.com, or http://182.167.1.1.
Note
Do not include any wildcard character, such as asterisk (*) in the URL.
The following image shows two URLs in which the button should be embedded:
Click Save.

Task 2: To include view-loader.js file in the application

Update the index.html file of the application.

Add the following <script> tag before closing the <body> tag:
<script id="rx-view-loader-script" src="https://hostname:port/innovationsuite/view-loader.js"></script>
<button class="rx-view-loader-button"data-bot-id="<Bot Id>"></button>
You can find the Bot ID from the webhook registration URL based on your authentication type. For more information about the webhook registration URL, see Registering a webhook with BMC Helix Platform to get real-time event notifications.
(Optional) If BMC Helix Platform is using Remedy SSO cloud native authentication application, add a <button> tag in the <body> tag, and specify the Remedy SSO server name as shown in the following example:
<button class="rx-view-loader-button" data-rsso-server="http://rsso.com:8080"></button>
Call the onRequestJwt API to register a callback function that returns a JWT token.
<script type="text/javascript">
       rxViewLoader.onRequestJwt(function () {
            // return JWT token
         });
</script>
Note
JWT tokens might quickly expire. Ensure that the callback function always returns a fresh and active token. The callback function is called every time the user clicks the BMC Helix Chatbot button. If the callback is not registered, or if it does not return a string, clicking the BMC Helix Chatbot button will have no effect, and an error will be logged in the browser console.

Task 3: To customize the embedded BMC Helix Chatbot button

As a developer, you can customize various properties of the embedded BMC Helix Chatbot button such as the icon, color, size, margin, and position of the chat panel. After customization, the default css class is overridden by the new one.

Best practice

We recommend to use a .PNG file with a transparent background.
The recommended dimensions of the icon are 150 pixels * 150 pixels. To avoid delays in loading the page, ensure that the new icon is not too big.

To open the chat panel on the left side of the page, specify the data-view-position attribute as shown in the following example:
<button class="rx-view-loader-button" data-view-position="left"></button>
To add a tooltip and an aria-label to the BMC Helix Chatbot button, add the corresponding attributes as shown in the following example:
<button class="rx-view-loader-button" title="Launch Chatbot" aria-label="Launch Chatbot"></button>
To change the color of the BMC Helix Chatbot button, add the following rules in your application CSS:
   .rx-view-loader-button {
      background-color: blue;
  border-color: darkblue;
    }
To change the icon, add the corresponding attributes and the css output that you copied earlier, as shown in the following example:
.rx-view-loader-button {
width: 150px;
height: 150px;
}
.rx-view-loader-button-icon {
background-image:css output
}

Example of customizing the BMC Helix Chatbot button

By default, when you embed BMC Helix Chatbot in a third-party application, the following icon is displayed:

Chatbot icon.png

This example explains how to change this default icon and embed the following icon:

Custom icon.png

To change the icon, perform the following tasks:

Convert the new icon to base64 by using a base64 converter, such as base64-image and copy the css code for future reference, as shown in the following example:

Add the following attributes to embed the new icon:

The following table explains the attributes in the above example and the customization achieved:

Attributes	Customization achieved
.rx-view-loader-button { width: 150px; height: 150px; }	Set the size of the button to 150 pixels.
.rx-view-loader-button-icon { background-image: url('data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAASwAAAEjCAYAAA ... AAAAASUVORK5CYII='); background-position-x: center; background-position-y: center; background-repeat-x: no-repeat; background-repeat-y: no-repeat; }	Set the css code of the custom icon that you copied from the base64 converter.
height: 150px;	Set the size of the icon to 150 pixels.
background-size: 150px 150px;	Set the picture dimension to 150 pixels*150 pixels.
<button class="rx-view-loader-button" title="Launch The Custom Bot" aria-label="Launch the Custom Bot"></button>	Set the tooltip for the custom icon.