Get Started

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;
  });
};