Bold360 AI Web API & SDK Reference Introduction

This Bold360 AI Web API and SDK reference documentation describes the events and methods your web pages can use to:

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:

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

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
ConversationalMode
   Search
SearchMode

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.

Event embeddedWidget floatingWidget
Conversational
floatingWidget
Search
Stage: Initializing - Set up and configure the widget
init Yes Yes Yes
Initializes the widget with configurations such as setting the initial context or enforcing a specific domain.
nanorep.embeddedWidget.on('init', function() {...})
nanorep.floatingWidget.on('init', function() {...})
Stage: Loading - After initializing is done, enter the widget into memory
load Yes Yes Yes
Executes after the widget is fully loaded and displayed to the user.
nanorep.embeddedWidget.on('load', function() {...})
nanorep.floatingWidget.on('load', function() {...})
Stage: Running - After initializing and loading are done, ready to execute the widget's methods and events
click for more events
click for more internal events

Widget Methods

The supportCenter widget supports only two methods:

 

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.

Signature

enableLogging() : 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.

Signature

setConfigId(configId) : void

Parameters

configId: String Config Id: The Domain API ID value shown in the Bold360 AI Console: TOUCHPOINTS > Widgets, choose your widget type, and select the Advanced tab
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

Signature

setInitializedEntities(params) : void

Parameters

params: Object Plain key-value Object

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.

Signature

setKB(kbId) : void

Parameters

kbId: String Knowledgebase Id: The Id or Name value returned by the Knowledge Bases - Get (getKBs) API call
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.

Signature

collapse() : void

nanorep.floatingWidget.collapse();
displayHeaderButtons No Yes No
Specify the buttons to show in the widget's header.

Signature

displayHeaderButtons(params) : void

Parameters

params: Object Plain key-value Object as shown below
params.close: Boolean Show (true) or hide (false) the close button. Default is false.
nanorep.floatingWidget.displayHeaderButtons({ close: true });
expand No Yes No
Enlarge the widget.

Signature

expand() : 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.

Signature

ask(query) : void

Parameters

query: String Query: Text to search for in the knowledge base
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.

Signature

focus() : 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:

  1. Set up the API.
  2. Initialize the API with common parameters.
  3. Register client-side entities and methods.
  4. Create the conversational session.
  5. 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);

Customize UI

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.

    Getting Started

    Channeling

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.

    Channeling and Feedback

    FAQ

    Feedback

    Lightbox

    Localization

    Query Field

    Sharing

    Styling

  

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:

  1. Set up the CCP.
  2. Call addChatProvider.
  3. Add CCP events and methods to your code.

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.

Signature

addChatProvider(providerName, providerProto) : void

Parameters

providerName: String Unique chat provider name
providerProto: Object Object with custom chat methods

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.

Signature

this.emit('agentTyping', state);

Parameters

state: Boolean Agent typing state
self.emit('agentTyping', true);
 availabilityChanged
Emit the availabilityChanged event to change the chat availability.

Signature

this.emit('availabilityChanged', state);

Parameters

state: Boolean Chat availability state
self.emit('availabilityChanged', true);
 chatEnded
Emit the chatEnded event to end the chat from the agent's side.

Signature

this.emit('chatEnded');

self.emit('chatEnded');
 chatStarted
Emit the chatStarted event to change the chat state from "waiting for agent" to "chat started".

Signature

this.emit('chatStarted');

self.emit('chatStarted');
 newMessage
Emit the newMessage event to add the message from the agent.

Signature

this.emit('newMessage', message);

Parameters

message: Object Object with text property
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.

Signature

constructor(channel) : void

Parameters

channel: Object Channel object
constructor: function(channel) {}
 endChat
Call the endChat method when the user wants to stop the chat with the agent.

Signature

endChat() : void

 getAgentName (Optional)
Get the agent name.

Signature

getAgentName(callback) : void

Parameters

callback: Function Function with agent name as the first parameter
getAgentName: function(callback) {
    callback('John Doe');
}
 getCapabilities
Activate capabilities. Must return an Object with specific capability settings.

Signature

getCapabilities() : Object

Return Object

Object Plain key-value Object as shown below
{ customUI: Boolean, vendorUI: Boolean, vendorPopup: Boolean }
customUI Indicates whether the provider supports seamless chat integration. A seamless integration means the chat provider operates with the nanorep widget/sdk.
vendorUI Indicates whether the provider supports nativeUI within the page. nativeUI refers to the UI that is native to the third-party chat provider. When the nativeUI launches, the Bold60 AI widget hides.
vendorPopup Indicates whether the provider can open a chat in a new window
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.

Signature

getChannelId(channel) : String

Parameters

channel: Object Plain key-value Object
getChannelId: function(channel) {
    return channel.providerName + channel.providerConfig;
}
                        
 isAvailable
Set up the callback to indicate whether the chat is available.

Signature

isAvailable(callback) : void

Parameters

callback: Function Function with Boolean as the first parameter to indicate whether the chat is available
isAvailable: function(callback) {
    //true indicates the chat is available
    callback(true);
}
 requestChat (Optional)
Request chat with an agent

Signature

requestChat() : void

requestChat: function() {
    //add anything here your provider requires
}
 sendMessage (Optional)
Send the message the user entered to the provider

Signature

sendMessage(message) : void

Parameters

message: Object An Object that must contain a text property
sendMessage: function(message) {  
  console.log('sending user message:', message,text);  
}
 setVisitorTyping (Optional)
Indicate when the user starts or stops typing

Signature

setVisitorTyping(isTyping) : void

Parameters

isTyping: Boolean Whether the user is typing (true=yes, false=no)
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

Signature

showVendorPopup() : 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

Signature

showVendorUI() : void

  showVendorUI: function() {
    console.log('activating chat in vendor UI...');
}

    Answer Wrapper

    Conversation Tool

    Library nr

    Quick Answer