This Bold360 AI Web API and SDK reference documentation describes the events and methods your web pages can use to:
- Control the behavior of Bold360 AI client-side web widgets through the Web API, and
- Interact with third-party chat providers and the Bold360 AI server to access the knowledge bases through the Web SDK. The Bold360 AI Console is where authorized personnel manage the knowledge bases (in the KNOWLEDGE menu) and control the look, feel, and operation of the widgets (in the TOUCHPOINTS menu).
Regarding this web page
INTERNAL NOTE: Because you specified internal=1 as an URL parameter, you will see sections in this color that are meant for internal LogMeIn staff.
The Expand all button at the upper-right (and elsewhere below) gives you an easy and quick way to expand all collapsed sections in this reference without having to individually expand them. When you click the button, its label changes to Collapse all so you can easily collapse all the sections you just expanded.
NOTE 1: To search for a term in this reference, click the Expand all button, and use your browser's Find function.
The navigation menu at the left provides a convenient way for you to locate reference topics.
NOTE 2: At the
bottom of the navigation menu is a Download Demo Code button you can click to save zipped source code that is working software. After
downloading, please unzip the file to your web server, open index.html in your browser, and follow its directions.
The examples shown on this page come from the zip file, where you would substitute the values in the following table with the values you
set for your environment. For example, if code on this page shows ...myAccount...
, you
should use your actual account name in the conf.js file from the downloaded zip file.
Example Value | Is ... |
---|---|
myAccount | Account Name: The name of the account the Bold360 AI system administrator assigns to your organization when it begins using the Bold360 AI product |
myConfigId | Config Id: The Domain API ID value shown in the Bold360 AI Console: TOUCHPOINTS > Widgets, choose your widget type, and select the Advanced tab |
myDomain | Domain Name: The DNS server name or IP address of the server for your organization provided by the Bold360 AI system administrator |
myKB | Knowledgebase Id: The Id or Name value returned by the Knowledge Bases - Get (getKBs) API call |
Regarding the Web API & SDK
To get more information beyond this reference, please refer to the API & SDK Guide. If you need even more help and support, please see the Official Help. You can also view the previous documentation.
Names of components, events, methods, and parameters are case sensitive.
All of the API and SDK components use the nanorep
namespace, because that was the original Bold360 AI
product name.
For specific information regarding the context parameter/field, please see the article What are Bold360 ai Contextual Answers?.
Note that knowledge base articles must be published and online to use them in the API and SDK. Sophisticated natural language algorithms match user entry in the widgets and components to the article Phrasings.
Web API
The Web API provides built-in, out-of-the-box JavaScript widgets you can add to your web pages to provide a user interface to the Bold360 AI knowledge base.
Widgets
The widgets are:
- Embedded Search Widget
- Embedded Support Center Widget
- Floating Widget
The Bold360 AI API & SDK Guide's Definitions topic describes the widgets in more detail.
Setup Code
Before using each widget, you must insert code into your web page to set up the widget.
Instructions
- Instead of copying code from this page and pasting it into your own files, it is much easier to download the working source code (as described in the note at the top of this page), and edit the conf.js file with your values. That way, you will get up and running in your own environment very fast only by changing a few lines of code.
- If you do copy and paste code from this page, you need to replace the values from the table at the top of this page with your own.
- Another way you can get code is by going to your Bold360 AI Console: TOUCHPOINTS > Widgets, choose your widget type*, and click the GET THE CODE button. However, the first bullet is our recommendation to get up and running the quickest. The TOUCHPOINTS > Widgets menu item appears in the Bold360 AI Console when your user settings allow it. If you do not see it, please contact your Customer Success Manager. *The Embedded Support Center widget is a special case; to get to its code you select TOUCHPOINTS > Support Center.
Embedded Search Widget
The nanorep.embeddedWidget
inserts a search box into your page. You must run a function similar to the one shown below
before you use this widget in your web page.
INTERNAL NOTE: The a
parameter
is useful to send the API calls to the apiHost instead of the regular host where you load the widgets from.
REMINDERS: ♦ Follow the Setup Instructions above. ♦ View or download the Demo Code at the bottom of the navigation menu.
<script> !function(t, e, o, c, n, a) { var s = window.nanorep = window.nanorep || {}; s = s[e] = s[e] || {}, s.apiHost = a, s.host = n, s.path = c, s.account = t, s.protocol = "https:" === location.protocol ? "https:" : "http:", s.on = s.on || function() { s._calls = s._calls || [], s._calls.push([].slice.call(arguments)) }; var p = s.protocol + "//" + n + c + o + "?account=" + t, el = document.createElement("script"); el.async = el.defer = !0, el.setAttribute("src", p), document.getElementsByTagName("head")[0].appendChild(el) }("myAccount", "embeddedWidget", "embedded-widget.js", "/web/", "myAccount.myDomain"); nanorep.floatingWidget.on({ init: function() { this.setKB(myKB); } }); </script>
After embedding the above code into your web page, you need to place the div
for the widget where you want it to appear, such as:
<p>Before the widget</p> <div id="nanorep-embedded-widget"></div> <p>After the widget</p>
Embedded Support Center Widget
The nanorep.supportCenter
widget embeds the entire Support Center website into your web page. Before using this widget,
you must add the following code to your web page where you need to specify your own values for the domain (support.nanorep.com)
and host (my.nanorep.com).
REMINDERS: ♦ Follow the Setup Instructions above. ♦ View or download the Demo Code at the bottom of the navigation menu.
<div id="nanorep-support-center"></div> <script> !function(t, e, o, n, c) { var s = window.nanorep = window.nanorep || {}; s = s[e] = s[e] || {}, s.host = c, s.path = n, s.domain = t, s.protocol = "https:" === location.protocol ? "https:" : "http:", s.on = s.on || function() { s._calls = s._calls || [], s._calls.push([].slice.call(arguments)) }; var a = document.createElement("script"); a.async = a.defer = !0, a.setAttribute("src", s.protocol + "//" + c + n + o), document.getElementsByTagName("head")[0].appendChild(a) }("support.nanorep.com","supportCenter","support-center.js","/web/","my.nanorep.com"); </script>
You can optionally set custom settings on this widget as shown below. Remember to use your own domain (supportCenterDomain) and host (mainSiteURL):
<script src="https://support.nanorep.com/web/support-center.js"></script> <script> nanorep.supportCenter.init({ noDirectDomainAccess: false, //use true to disable direct access to the support center domain to make it available only as an embedded block on the page supportCenterDomain: 'support.nanorep.com', mainSiteURL: 'my.nanorep.com', urlPrefix: '#/path' }); </script>
For more information, please see Technical Preparations to implement a support center.
Floating Widget
The nanorep.floatingWidget
enables your users to ask questions and receive answers from the knowledge base.
You must run a function similar to the one shown below before you use this widget in your web page. This code is very
similar to the Embedded Search Widget setup code except a div
is not used.
INTERNAL NOTE: The a
parameter
is useful to send the API calls to the apiHost instead of the regular host where you load the widgets from.
REMINDERS: ♦ Follow the Setup Instructions above. ♦ View or download the Demo Code at the bottom of the navigation menu.
<script> !function(t, e, o, c, n, a) { var s = window.nanorep = window.nanorep || {}; s = s[e] = s[e] || {}, s.apiHost = a, s.host = n, s.path = c, s.account = t, s.protocol = "https:" === location.protocol ? "https:" : "http:", s.on = s.on || function() { s._calls = s._calls || [], s._calls.push([].slice.call(arguments)) }; var p = s.protocol + "//" + n + c + o + "?account=" + t, el = document.createElement("script"); el.async = el.defer = !0, el.setAttribute("src", p), document.getElementsByTagName("head")[0].appendChild(el) }("myAccount", "floatingWidget", "floating-widget.js", "/web/", "myAccount.myDomain"); </script>
After embedding the above code into your web page, you need to initialize and configure your widget similar to thie following, which is
shown in the init
event in the Widget Events table and the setKB
method in
the Widget Methods table.
nanorep.floatingWidget.on({ init: function() { this.setKB(myKB); } });
The floatingWidget
operates in two modes: Conversational or Search. The mode is controlled in the
Bold360 AI Console: TOUCHPOINTS > Widgets > Floating widget > Personalize > Select a knowledge base or URL to customize,
and scroll down to the Widget Mode on the Basics tab. If you do not see the Widget Mode, choose a
different Skin.
Conversational mode causes the widget to make the knowledge base
articles look like messages being exchanged in a chat. Search mode causes the articles to be displayed on top of each other. The following
shows the two modes after entering first "example1" and then "example2" in the widget. For more information, please see the Setup
Code topic.
Conversational |
Search |
Widget Events
The supportCenter
widget supports only one event, init
:
nanorep.supportCenter.on('init', function() {...})
The following table shows the events supported in each widget lifecycle stage
and the floatingWidget
's mode.
click for more internal events |
Widget Methods
The supportCenter
widget supports only two methods:
-
enableLogging
Signature
enableLogging() : void
nanorep.supportCenter.enableLogging();
-
scrollTo
Signature
scrollTo() : void
nanorep.supportCenter.scrollTo();
The following table shows the methods supported in each widget lifecycle stage
and the floatingWidget
's mode (as described above).
Method | embeddedWidget | floatingWidget Conversational |
floatingWidget Search |
|||||
---|---|---|---|---|---|---|---|---|
Stage: Any/All | ||||||||
enableLogging | Yes | Yes | Yes | |||||
Enable logging of debug
information to the browser's console.
SignatureenableLogging() : void |
||||||||
nanorep.embeddedWidget.enableLogging(); |
||||||||
nanorep.floatingWidget.enableLogging(); |
||||||||
Stage: Initializing - Set up and configure the widget | ||||||||
setConfigId | Yes | Yes | Yes | |||||
Instruct the widget to use a
specific domain API ID.
SignaturesetConfigId(configId) : void Parameters
|
||||||||
nanorep.embeddedWidget.setConfigId(myConfigId); |
||||||||
nanorep.floatingWidget.setConfigId(myConfigId); |
||||||||
setInitializedEntities | No | Yes | No | |||||
Set entity values for use in conversations.
You can use entity names (the keys in the key-value pairs) as placeholders in articles by surrounding them with double brackets, like [[thisEntityName]]. When you have an article that uses placeholders in the text, the floatingWidget shows the values you set in this method instead of the placholders. Note that in the Bold360 AI Console's Article Editor, when entering Content and you type two left-brackets, a drop-down list of all entity names you have set in the KNOWLEDGE > Entities menu appears. You can choose one or type a new one
SignaturesetInitializedEntities(params) : void Parameters
|
||||||||
For this example, let's say your article's content is "Hi [[userFirstName]]. I see you are a [[role]]." When the article displays in the floatingWidget, it looks like "Hi SampleFirstName. I see you are a SampleRole." nanorep.floatingWidget.setInitializedEntities({ userFirstName: 'SampleFirstName', role: 'SampleRole' }); |
||||||||
setKB | Yes | Yes | Yes | |||||
Instruct the widget to use a
specific knowledge base.
SignaturesetKB(kbId) : void Parameters
|
||||||||
nanorep.embeddedWidget.setKB(myKB); |
||||||||
nanorep.floatingWidget.setKB(myKB); |
||||||||
Stage: Loading - After initializing is done, enter the widget into memory | ||||||||
collapse | No | Yes | No | |||||
Contract the widget.
Signaturecollapse() : void |
||||||||
nanorep.floatingWidget.collapse(); |
||||||||
displayHeaderButtons | No | Yes | No | |||||
Specify the buttons to show in the widget's header.
SignaturedisplayHeaderButtons(params) : void Parameters
|
||||||||
nanorep.floatingWidget.displayHeaderButtons({ close: true }); |
||||||||
expand | No | Yes | No | |||||
Enlarge the widget.
Signatureexpand() : void |
||||||||
nanorep.floatingWidget.expand(); |
||||||||
setInitializedEntities - see Initializing Stage | No | Yes | No | |||||
Stage: Running - After initializing and loading are done, ready to execute the widget's methods and events | ||||||||
addChatProvider - see Custom Chat Provider | Yes | Yes | Yes | |||||
ask | Yes | Yes | No | |||||
Cause the widget to query the
knowledge base based on the supplied text.
Signatureask(query) : void Parameters
|
||||||||
nanorep.embeddedWidget.ask('please help?'); |
||||||||
nanorep.floatingWidget.ask('please help?'); |
||||||||
collapse - see Loading Stage | No | Yes | No | |||||
expand - see Loading Stage | No | Yes | No | |||||
focus | Yes | Yes | No | |||||
Activate the widget so the user can enter text in it.
Signaturefocus() : void |
||||||||
nanorep.embeddedWidget.focus(); |
||||||||
nanorep.floatingWidget.focus(); |
||||||||
click for more methods |
click for more internal methods |
displayHeaderButtons
displayHeaderButtons(params) : void
Specify which buttons should be shown in header of floating widget
Parameters
params: Object |
Plain key-value Object |
params.close: Boolean |
Show or hide close button |
params.minimize: Boolean |
Show or hide minimize button |
params.expand: Boolean |
Show or hide expand button |
nanorep.floatingWidget.on('load', function() { this.displayHeaderButtons({ close: true, minimize: true, expand: true }); });
getEntities
getEntities(params) : Promise
Retrieves entity values related to the specified conversation. Params will be sent to the /api/conversation/v1/getEntities
API endpoint. (Note: /api/conversation/v2/getEntities
API endpoint is in introduction phase.)
(This method works only in "conversational" widget mode)
Parameters
params: Object (optional) |
Optional argument. Provide key-value Object and all its params will be forwarded to the remote API endpoint (by default widget will automatically send current "Conversation ID" if conversation is already created). |
nanorep.floatingWidget.api.conversation.getEntities().then(function(response){ console.log(response); });
setMetaData
setMetaData(params) : void
Specify object with additional parameters to be added to /api/conversation/v1/create
API call
Parameters
params: Object |
Plain key-value Object |
nanorep.floatingWidget.setMetaData({ key1: 'value1', key2: 'value2' });
useCloseConfirmation
useCloseConfirmation(state) : void
Method specifies confirmation form should be shown or not
Parameters
state: Boolean |
Show confirmation form when user is trying to close widget by clicking on close button |
nanorep.floatingWidget.on('load', function() { this.useCloseConfirmation(true); });
Conversational API
The nanorep.api.conversation
API allows the integration of conversational/chat bot capabilities into existing applications. It
provides a set of methods and hooks to process conversations including the management of client-side entities.
REMINDER: View or download the Demo Code at the bottom of the navigation menu.
Follow the steps below to use this API:
- Set up the API.
- Initialize the API with common parameters.
- Register client-side entities and methods.
- Create the conversational session.
- Chat.
Set up the API
<script src="myAccount.myDomain/web/include.js?api=conversation"/>
Initialize the API with Common Parameters
nanorep.api.init({ enableJSONPProxy: false, //set to true to enable <iframe> proxy for JSONP requests (enable API usage in environments with strict Content Security Policy, such as Firefox OS) host: 'myAccount.myDomain', account: 'myAccount', kb: 'myKB' });
Register Client-side Entities and Methods
Define client-side entites in a plain object where keys are entity names that are placeholder patterns, and values are functions that return corresponding entity data. It is also possible to return a Promise with entity data when asynchronous operation is needed. You can use entity names (the keys in the key-value pairs) as placeholders in articles by surrounding them with double brackets, like [[thisEntityName]]. When you have an article that uses placeholders in the text, the API shows the values you set in this method instead of the placholders. Note that in the Bold360 AI Console's Article Editor, when entering Content and you type two left-brackets, a drop-down list of all entity names you have set in the KNOWLEDGE > Entities menu appears. You can choose one or type a new one
Signature
nanorep.api.conversation.registerClientEntities(entities: Object) : void
Parameters
entities: Object |
Plain key-value Object |
nanorep.api.conversation.registerClientEntities({ SUBSCRIBERS: function(response) { //return data synchronously return { "kind": "SUBSCRIBERS", "type": "number", "value": "3", "lifecycle": "persistent", "confidence": 1, "properties": [{ "kind": "SUBSCRIBER", "type": "number", "value": "50123456789", "name": "50123456789", "properties": [{ "kind": "ID", "type": "number", "value": "50123456789" }] }, { "kind": "SUBSCRIBER", "type": "number", "value": "5011111111", "name": "5011111111", "properties": [{ "kind": "ID", "type": "number", "value": "5011111111" }] }, { "kind": "SUBSCRIBER", "type": "number", "value": "5222222222", "name": "5222222222", "properties": [{ "kind": "ID", "type": "number", "value": "5222222222" }] }] }; }, BALANCE_TYPE: function() { //async Promises are also supported return Promise.resolve({ "kind": "BALANCE_TYPE", "type": "number", "value": "-1" }); } });
Define the set of client-side methods. These methods are invoked to get the value of article patterns like {{ getBalance([[SUBSCRIBER.ID]]) }}. Keys of method objects are method names and values are the methods themselves.
Signature
nanorep.api.conversation.registerClientMethods(methods: Object) : void
Parameters
methods: Object |
Plain key-value Object |
nanorep.api.conversation.registerClientMethods({ getBalance: function(subscriberId, balanceType) { //sync return and async Promises are supported switch (subscriberId) { case 50123456789: return '$1200 ' + balanceType; case 5011111111: return '$0.99 ' + balanceType; case 5222222222: return '$7 ' + balanceType; default: return 'hidden'; } } });
Create the Conversational Session
Start a new session, and get a Conversation Id that is required in the other conversational API calls.
Signature
nanorep.api.conversation.create() : Object
Parameters
entities: Object |
Plain key-value Object |
initConversation: function() { //create conversation if not created yet var self = this; if (!this.initRequest) { this.initRequest = nanorep.api.conversation.create().then(function(response) { self.conversationId = response.id; }); } return this.initRequest; };
Chat
Send user queries to the chat bot and receive responses from the bot through addStatement or sendMessage.
Signature
nanorep.api.conversation.addStatement(params: Object) : Promise
Parameters
params: Object |
Plain key-value Object as shown below |
params.id: Number |
(REQUIRED) The Conversation Id returned from the nanorep.api.conversation.create() call |
params.statement: String |
(REQUIRED) Query text to search for in the knowledge base |
params.postback: Postback |
(Optional) Postback |
nanorep.api.conversation.addStatement({ id: self.conversationId, statement: 'hello' }).then(...)
Signature
nanorep.api.conversation.sendStatement(message) : void
Parameters
message: String |
The text to send |
this.sendMessage(action.text);
The useCustomUI
class helps you customize
the floatingWidget
's UI when it is in Conversational mode (explained
above). To use the class, you must call its constructor
method.
Web SDK
The Web SDK provides built-in, out-of-the-box functionality in the nanorep.api
and nanorep.sdk
namespaces
for interacting with third-party chat providers and the Bold360 AI server to access the knowledge base. If you are
looking for the iOS or Android SDKs, you can find them in
the Bold360 AI Mobile SDK topic.
Bold360 AI provides a variety of channels you can use to directly communicate with your web users before they ever need to escalate contact to an agent. The administrator manages the channels in the Bold360 AI Console.
Custom Chat Provider
The Custom Chat Provider (CCP) provides ways for you to implement and customize channeling policies you wish to use with third-party chat providers.
REMINDER: View or download the Demo Code at the bottom of the navigation menu.
Follow the steps below to use the CCP:
Set up the CCP
To use the Custom Chat Provider (CCP) with the nanorep.sdk
, add the following to the top of your web page:
<script type="text/javascript" src="https://myAccount.myDomain/web/include.js?sdk=channeling-bar"></script>
To use the CCP with the embedded and floating widgets, no additional setup code is needed other than what the Setup Code topic describes.
Regardless of using the nanorep.sdk
or the widgets, you should create a channeling policy for your chat provider. For information, please see the Channeling Policy procedure.
addChatProvider
To integrate the SDK or the embedded and floating widgets with CCPs, each touchpoint (nanorep.sdk
, nanorep.embeddedWidget
, and nanorep.floatingWidget
) requires you to call addChatProvider()
in which you call the constructor()
method and other CCP events and methods.
Add the custom chat provider to the web page or widget.
SignatureaddChatProvider(providerName, providerProto) : void Parameters
|
CCP Events
We use the emit
function to trigger all CCP events that apply to the sdk, embeddedWidget, and floatingWidget..
agentTyping | |||
Emit the agentTyping event to show agent typing activity.
Signaturethis.emit('agentTyping', state); Parameters
self.emit('agentTyping', true); |
|||
availabilityChanged | |||
Emit the availabilityChanged event to change the chat availability.
Signaturethis.emit('availabilityChanged', state); Parameters
self.emit('availabilityChanged', true); |
|||
chatEnded | |||
Emit the chatEnded event to end the chat from the agent's side.
Signaturethis.emit('chatEnded'); self.emit('chatEnded'); |
|||
chatStarted | |||
Emit the chatStarted event to change the chat state from "waiting for agent" to "chat started".
Signaturethis.emit('chatStarted'); self.emit('chatStarted'); |
|||
newMessage | |||
Emit the newMessage event to add the message from the agent.
Signaturethis.emit('newMessage', message); Parameters
self.emit('newMessage', { text: 'Hello there! Type anything, and I will reply!' }); |
CCP Methods
All CCP methods apply to the sdk, embeddedWidget, and floatingWidget.
constructor | |||||||||||
Initialize the chat provider instance.
Signatureconstructor(channel) : void Parameters
constructor: function(channel) {} |
|||||||||||
endChat | |||||||||||
Call the endChat method when the user wants to stop the chat with the agent.
SignatureendChat() : void |
|||||||||||
getAgentName (Optional) | |||||||||||
Get the agent name.
SignaturegetAgentName(callback) : void Parameters
getAgentName: function(callback) { callback('John Doe'); } |
|||||||||||
getCapabilities | |||||||||||
Activate capabilities. Must return an Object with specific capability settings.
SignaturegetCapabilities() : Object Return Object
getCapabilities: function() { return { customUI: true, //true = the provider supports seamless chat integration vendorUI: false, //false = the provider does not support nativeUI within the page vendorPopup: false //false = the provider cannot open a chat in a new window } } |
|||||||||||
getChannelId (Optional) | |||||||||||
Control the number of instances of this chat provider that can be created. The default is one (singleton). If called, this must return a unique key for each instance based on the channel Object parameter.
SignaturegetChannelId(channel) : String Parameters
getChannelId: function(channel) { return channel.providerName + channel.providerConfig; } |
|||||||||||
isAvailable | |||||||||||
Set up the callback to indicate whether the chat is available.
SignatureisAvailable(callback) : void Parameters
isAvailable: function(callback) { //true indicates the chat is available callback(true); } |
|||||||||||
requestChat (Optional) | |||||||||||
Request chat with an agent
SignaturerequestChat() : void requestChat: function() { //add anything here your provider requires } |
|||||||||||
sendMessage (Optional) | |||||||||||
Send the message the user entered to the provider
SignaturesendMessage(message) : void Parameters
sendMessage: function(message) { console.log('sending user message:', message,text); } |
|||||||||||
setVisitorTyping (Optional) | |||||||||||
Indicate when the user starts or stops typing
SignaturesetVisitorTyping(isTyping) : void Parameters
setVisitorTyping: function(isTyping) { console.log('user is typing?:', isTyping); } |
|||||||||||
showVendorPopup (Optional) | |||||||||||
When the provider has a pop-up capability, call this method when activating the chat
SignatureshowVendorPopup() : void showVendorPopup: function() { console.log('activating chat in popup window...'); } |
|||||||||||
showVendorUI (Optional) | |||||||||||
When the provider has UI capability, call this method when activating the chat
SignatureshowVendorUI() : void showVendorUI: function() { console.log('activating chat in vendor UI...'); } |