×
 
 
  •  
$helper.renderConfluenceMacro('{bmc-global-announcement:$space.key}')

 

This documentation supports the 20.08 version of BMC Helix Chatbot.
To view the documentation for the previous version, select 20.02 from the Product version menu.
BMC Helix Chatbot 20.08 Integrating BMC Helix Chatbot with other applications

Embedding BMC Helix Chatbot in external applications

As a developer, you can embed an external application, which is not developed on the BMC Helix Platform, on the BMC Helix Chatbot UI. You can also configure multiple chatbots for different lines of business and embed these chatbots in an application by using a customized icon or menu. 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 Open link .

Process 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:

TaskRoleProductActionReference
1Administrator

BMC Helix Innovation Studio

Register the application URL in which you want to embed the BMC Helix Chatbot UI.

To register the application URL

2Application developerindex.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 developerindex.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. 

  1. Log in to BMC Helix Innovation Studio and navigate to the Administration tab. 
  2. Select Configure My Server > Helix Platform > Iframe Security.

  3. On the Iframe Security page, select Trusted web applications allowed to display BMC Helix Platform views section.

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

    Important

    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:

  5. Click Save.

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

Update the index.html file of the application to add the BMC Helix Chatbot button, and register a function that returns a JWT token if you register Remedy SSO server.

  1. 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 only by launching the chatbot from the bundle where the chatbot is configured. 

  2. Add the following HTML code to embed one or multiple chatbots in an application by using a customized icon, button, or menu for BMC Helix Chatbot:

    ActionScript
    To embed a single chatbot.
    <button class="rx-view-loader-button"data-bot-id="<Bot Id>"></button>
    To embed a chatbot list that will be displayed in the chatbot icon contextual menu.
    <button class="rx-view-loader-button" data-bot-list='[{"name": "<chatbotName>", "botId": "<Bot Id>"}, {"name": "<chatbotName>","botId": "<Bot Id>"}]'></button>

    Important: You can use the data-bot-list parameter only for the BMC out-of-the-box default chatbot button.

    To use your own contextual menu, buttons, or links to open a chatbot.
    <br>Links using menu class<br>
<a href="#" class="rx-view-loader-launch-bot" data-bot-id="<Bot Id>"><chatbotName></a><br/>
<a href="#" class="rx-view-loader-launch-bot" data-bot-id="<Bot Id>">chatbotName></a><br/>
<a href="#" class="rx-view-loader-launch-bot" data-bot-id="<Bot Id>" data-rsso-server="<serverName>"><chatbotName></a><br/>
<a href="#" class="rx-view-loader-launch-bot">default</a><br/>
<a href="#" class="rx-view-loader-launch-bot" data-rsso-server="<serverName>">default with RSSO</a><br/>
<a href="#" class="rx-view-loader-launch-bot" data-embedded-authentication="false">default bot with an IDP that cannot be embedded in an iFrame</a><br/>

    Important:

    • Make sure you use the class rx-view-loader-launch-bot for using your own HTML elements. The class rx-view-loader-button is dedicated to the BMC out-of-the-box default button.
    • The class rx-view-loader-launch-bot can be implemented in multiple HTML elements so you as a developer can create your own menu or links.
    • The class rx-view-loader-button can be implemented in only one HTML element to define the BMC out-of-the-box default chatbot button.

    • The rxLaunchBot() javascript uses the following optional parameters:

      rxLaunchBot(botId, rssoServerUrl, embeddedAuthentication)


    <br>Links calling javascript rxLaunchBot<br>
<a onclick="rxLaunchBot('<Bot Id>')" href="#"><chatbotName></a><br/>
<a onclick="rxLaunchBot('<Bot Id>', '<rssoServer>')" href="#"><chatbotName> with RSSO</a><br/>
<a onclick="rxLaunchBot()" href="#">Opening default Chatbot</a><br/>
<a onclick="rxLaunchBot('', '<rssoServer>')" href="#">default Chatbot with RSSO</a><br/>
<button onclick="rxLaunchBot('', '', false)">default Chatbot and authentication is done in a popup</button><br/>

    Important:

    • The rxLaunchBot() javascript uses the following optional parameters:

      rxLaunchBot(botId, rssoServerUrl, embeddedAuthentication)

    • When you configure custom chatbot, by default the authentication takes place in the iFrame. If your organization's Identity Provider (IDP) does not allow to be displayed in an iFrame, see Troubleshooting.

  3. (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>

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

    Important

    • The callback function returns a JWT token only if you have defined the data-rsso-server parameter while embedding one or multiple chatbots in an application.
    • 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.
CustomizationSample script
To open the chat panel on the left side of the page, specify the data-view-position attribute.
<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.

<button class="rx-view-loader-button" title="Launch Chatbot" aria-label="Launch Chatbot"></button>
To define a custom contextual menu icon for a chatbot.
<button class="rx-view-loader-button" data-bot-list='[{"name": "HR Bot", "botId": "<Bot ID>"}, {"name": "HR Bot2", "botId": "<Bot ID>", "iconClassName": "my-custom-icon"}]'></button>

Custom CSS class:

.my-custom-icon {
    background: url('data:image/png;base64,iVBOR...ErkJggg==') no-repeat;
    height: 20px;
    width: 20px;
    margin-left: 15px;
    background-size:20px;
    cursor: pointer;
}

To change the color of the BMC Helix Chatbot button.

.rx-view-loader-button {
    background-color: blue;
	border-color: darkblue;
  }
To change the default chatbot contextual menu icons.
.rx-green-bot {
    background: url('data:image/png;base64,iVBORw...CC') no-repeat;
    height: 20px;
    width: 20px;
    margin-left: 15px;
    background-size:20px;
    cursor: pointer;
}

You can update rx-green-bot, rx-yellow-bot, or rx-blue-bot classes.

Example:  Customizing the BMC Helix Chatbot button

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

To change the default icon with a custom icon such as  and embed this custom icon, perform the following steps:

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

  2. Add the following attributes to embed the new icon:

    <style>
.rx-view-loader-button {
width: 150px;
height: 150px;
}
.rx-view-loader-button-icon {
background-image:
url('data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAASwAAAEjCAYAAACIKzygAAAACXBIWXMAAA7DAAAOwwHHb6hkAA
...
AAAAASUVORK5CYII=');
background-position-x: center;
background-position-y: center;
background-repeat-x: no-repeat;
background-repeat-y: no-repeat;
height: 150px;
background-size: 150px 150px;
}
</style>
<script id="rx-view-loader-script" src="https://hostname/innovationsuite/view-loader.js"></script>
<button class="rx-view-loader-button" title="Launch The Custom Bot" aria-label="Launch the Custom Bot"></button>

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

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

Example: Creating a menu to list chatbots for multiple lines of business

The following table displays how you can embed multiple chatbots in a single button or custom menu:

ActionExampleSample Code

To display custom chatbot menu that opens the selected chatbot in the iFrame.

<span class="rx-view-loader-launch-bot">Default Bot</span>
 <span class="rx-view-loader-launch-bot" data-bot-id="<HR Bot ID>">HR Bot</span>
 <span class="rx-view-loader-launch-bot" data-bot-id="<IT Bot India ID>" >IT Bot (India)</span>
 <span class="rx-view-loader-launch-bot" data-bot-id="<IT Bot ID EMEA>">IT Bot (EMEA)</span>

To display custom chatbot menu that opens the selected chatbot in the iFrame.

The Remedy SSO native authentication is opened in a pop-up window rather than in an iFrame.



<span class="rx-view-loader-launch-bot" data-bot-id="<HR Bot ID>" data-embedded-authentication="false">HR Bot</span>
<span class="rx-view-loader-launch-bot" data-bot-id="<IT Bot India ID>" data-embedded-authentication="false">IT Bot (India)</span>
<span class="rx-view-loader-launch-bot" data-bot-id="<IT Bot EMEA ID>" data-embedded-authentication="false">IT Bot (EMEA)</span>



To display chatbot contextual menu with customized chatbot icons.

<style>
/* Heart icon replaces the BMC Green bot icon */
.rx-green-bot{background: url('data:image/png;base64,iVBORw0KGB(...)5ErkJggg==') no-repeat;
 height: 20px;
 width: 20px;
 margin-left: 15px;
 background-size:20px;
 cursor: pointer;
}
/* Custom contextual menu icon */
.rx-custom-bot-icon {background: url('data:image/png;base64,iVBORw0KGg(...)5ErkJggg==') no-repeat;
 height: 20px;
 width: 20px;
 margin-left: 15px;
 background-size:20px;
 cursor: pointer;
}
</style>

<button class="rx-view-loader-button"
 data-bot-list='[{"name": "HR Bot", "botId": "<HR Bot ID>"},
 {"name": "IT Bot (India)", "botId": "<IT Bot India Bot ID>"},
 {"name": "IT Bot (EMEA)", "botId": "<IT Bot EMEA Bot ID>", "iconClassName": "rx-custom-bot-icon"}]'
 data-embedded-authentication="false"></button>

Troubleshooting

Your organization's Identity Provider (IDP) does not allow the chatbot to be displayed in an iFrame

When you configure a custom chatbot menu that opens the selected chatbot in an iFrame, by default the Remedy SSO native authentication is opened in an iFrame. If your organization's IDP does not allow the authentication to be displayed in an iFrame, you can set the parameter data-embedded-authentication="false" that displays the authentication in a pop-up window.

When you launch the chatbot, a pop-up window is displayed to check if the user is authenticated or not. If the user is authenticated, the pop-up window closes automatically and the chatbot is displayed in an iFrame.

If the user is not authenticated, the IDP login page is displayed. After the user logs in and is authenticated successfully, the pop-up window closes and the chatbot is displayed in an iFrame.

Enabling cross-origin support (CORS) in Internet Explorer 11

Internet Explorer 11 does not support CORS by default. To enable CORS in Internet Explorer 11, perform the following steps:

  1. Open Internet Explorer 11.
  2. Select Tools > Internet Options.
  3. On the Security tab, clear the Enable Protected Mode (requires restarting Internet Explorer) check box.
  4. Click Custom level.
  5. In the Settings section, from Miscellaneous > Access data sources across domains, select Enable check box.
  6. Click OK, and, if prompted, confirm that you want to change the settings for the zone.
  7. Click OK.
  8. Restart Internet Explorer.

Unable to log in to embedded BMC Helix Chatbot when accessing a third party application by using the Safari browser

When you access a third party application from the Safari browser and try to log in to the embedded BMC Helix Chatbot, the login screen enters an infinite loop.

To overcome this issue, perform the following steps in the Safari browser:

  1. Open the Safari browser.
  2. Select Preferences > Privacy.
  3. Clear the selected Prevent cross-site tracking checkbox.
    The following image shows the Privacy tab of a Safari browser window.

Related topics

Integrating BMC Digital Workplace Catalog with BMC Helix Chatbot Open link

Troubleshooting BMC Helix Chatbot issues

Troubleshooting Remedy Single Sign-On issues

Was this page helpful? Yes No Submitting... Thank you
Last modified by Prachi Kalyani on Sep 23, 2020
embed_chatbot add_chatbot_button javascript ba externallink tasks thirdpartylink best_practices troubleshooting idp enable cross-origin cors iframe multiple_chatbots

Comments

Log in or register to comment.

Enabling live chat for users
Administering
© Copyright 2017 - 2022 BMC Software, Inc.
Legal notices

Powered by Atlassian Confluence and Scroll Viewport

© Copyright 2005-2024 BMC Software, Inc. Use of this site signifies your acceptance of BMC’s Terms of Use . BMC, the BMC logo, and other BMC marks are assets of BMC Software, Inc. These trademarks are registered and may be registered in the U.S. and in other countries.