- 26 Apr 2022
- 5 Minutes to read
- Print
- DarkLight
Get Started
- Updated on 26 Apr 2022
- 5 Minutes to read
- Print
- DarkLight
Get Started
Where to define code
To use Comm100 Live Chat API, you can either write the code on your own page, or define the code
in your Control Panel. If you define the code on your own page, the code will be available for
chat button, invitation and embedded chat window. However, pop up chat window is not included.
If you would like to use API for pop up chat window as well, you need to define the code in your
Control Panel.
To define code in your Control Panel, please first login here,
then goes to "LiveChat" >> "Campaign" >> "Chat Window" >> "Advanced" >> "Add custom JavaScript to my chat window".
How to call API
Comm100 Live Chat API needs time to load. You can only use APIs when it's fully ready. Thus, it's
recommended for you to wrap your call with a callback function that is assigned to Comm100API.onReady
.
Comm100 Live Chat will trigger this callback when everything is ready.
Example as shown below:
Comm100API.onReady = function () {
// use API here safely
};
What APIs provided
Comm100 Live Chat provides 5 fundamental APIs to help you gain control of your chat on site.
Get
To get necessary information, you could use Comm100API.get
:
/**
* @param {string} type - Type of data to get, you can find all types in doc below.
* @param {...any} args - Any specific argument required.
* @return {any} result.
*/
Comm100API.get('type', ...args);
For example,
Comm100API.get('livechat.button.isVisible', campaignId);
will tells you whether button with campaign ID equals to campaignId
is visible.
Set
To set info into chat system, you could use Comm100API.set
:
/**
* @param {string} type - Type of data to set, you can find all types in doc below.
* @param {any} value - Value that will be set.
* @param {...any} args - Any additional arguments required by API.
*/
Comm100API.set('type', value, ...args);
For example,
Comm100API.set('livechat.button.isVisible', campaignId, true);
will set button with campaign ID equals to campaignId
as visible.
Event
If you would like to listen to specific event, you could use Comm100API.on
:
/**
* @param {string} type - Type of event you would like to listen to, you can
* find all types in doc below.
* @param {function} callback - Subscription function, which will be triggered when
* event fires.
* @return {function} unregistration - Unsubscribe callback, stops listening to
* this event.
*/
Comm100API.on('type', callback);
For example,
Comm100API.on('livechat.dynamicCampaign.change', function (currentCampaignId) { });
will register subscription function which listens to dynamic campaign changes. It will be triggered
whenever campaign ID changes, and current campaign ID will be provided as parameter.
Replace Element
Comm100 Live Chat provides custom CSS feature to allow modification of live chat components. If you
would like to use your own component instead of modifying the style of existing one, you could use
Comm100API.render
:
/**
* @param {string} type - Type of component you would like to replace, you can find
* all types in doc below.
* @param {function} callback - Callback function which will be used to generate
* custom component for replacement. If HTMLElement is returned in this callback,
* it will be used to replace default component; If falsy value is returned, default
* component will be used instead.
*/
Comm100API.render('type', callback);
For example,
Comm100API.render('livechat.invitation.popupImage', function () {
const customComponent = document.createElement('div');
return customComponent;
});
will replace image invitation with custom component returned by this callback function.
Act
You might want to manually trigger some actions, instead of waiting for visitor to do it. To do this,
you could use Comm100API.do
:
/**
* @param {string} type - Type of action to do, you can find all types in doc below.
* @param {...any} args - Any argument required.
* @return {Promise<void> | void} Promise which indicates whether async action is
* finished successfully or not. For sync actions, nothing will be returned.
*/
Comm100API.do('type', ...args);
For example,
Comm100API.do('livechat.button.click', campaignId);
will trigger action, the same as visitor click on button with campaign ID campaignId
.
Examples
Below are two typical examples of how to use custom JavaScript.
Dynamically Change Options based on User Input
One powerful feature of JavaScript is that it allows you to implement inter-dependent select menus,
where the select of one menu changes the contents of another.
For example, you have placed a Product Service field (dropdown list) on your pre-chat form. When
visitors select Live Chat, the 4th Field will show; when visitors select other options in the
Product Service field, the 5th Field will show.
/**
* Display either 4th Field or 5th Field based on the select result in Product Service field.
*/
Comm100API.onReady = function () {
function fieldDisplay(field) {
// check if current field is Product Service
if (field.label !== 'Product Service') return;
var fields = Comm100API.get('livechat.prechat.fields');
// check if current selected value is 'livechat'
if (field.value === 'livechat') {
// display/hide fields accordingly
fields[3].isHidden = false; // 4th field
fields[4].isHidden = true; // 5th field
} else {
fields[3].isHidden = true;
fields[4].isHidden = false;
}
Comm100API.set('livechat.prechat.fields', fields);
}
Comm100API.on('livechat.prechat.field.change', fieldDisplay);
Comm100API.on('livechat.prechat.display', function () {
var fields = Comm100API.get('livechat.prechat.fields');
fields.forEach(fieldDisplay);
});
};
Dynamically Insert Custom Fields and Submit
Imagine that you could insert custom fields in your post-chat survey, and then the collected
visitors' feedback would also be available in your Comm100 account.
Here is how custom JavaScript can help you:
Note: To make sure that Comm100 server can store the value of your custom fields correctly, the
value your visitors input in custom fields needs to be insert into Comm100 Post Chat fields before
submit. This means that you need to add the corresponding fields in Comm100 Post Chat Window,
mapping with your own custom fields. Click here to learn how to add fields to your post-chat window.
Comm100API.onReady = function () {
/**
* Set specific value in field named text
* @param {string} val - Value that will be set into field
*/
function setValue(value) {
var fields = Comm100API.get('livechat.postChat.fields');
Comm100API.set('livechat.postChat.fields', fields.map(function (field) {
if (field.label !== 'text') return field;
field.value = value;
return field;
}));
}
/** Use custom fields in post chat intead of default one */
Comm100API.render('livechat.postChat.form', function () {
/** Create custom fields */
var container = document.createElement('div');
container.id = 'customPostChatContainer';
container.innerHTML =
'<table><tr><td>Post Example:</td><td><input id="customerName"/></td></tr></table>';
/** Register event callbacks */
container.getElementsByTagName('input')[0].addEventListener('change', function () {
/** Save visitors' input back to Comm100 post chat fields */
setValue(this.value);
}, true);
/** Render custom fields */
return container;
});
};