Pre-Chat

Pre-Chat

Skip PreChat

To skip pre chat:

/** @type {boolean} */
const isPrechatSkipped = true;
Comm100API.set('livechat.prechat.isSkip', isPrechatSkipped);

Please notice that prechat forms need to be filled with correct data to ensure that skipping prechat
can work. That means, if there is any required field with empty value, or if there is invalid email
address in email field, etc., skipping prechat will fail and prechat will still be shown.

To fill prechat form with data, please check the API below.

To see if pre-chat has been set to skip:

/** @type {boolean} */
const isPrechatSkipped = Comm100API.get('livechat.prechat.isSkip');

Fields

Get All Fields

You could get all fields in prechat using API:

/** @type {string} */
const campaignId = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx';
/** @type {Array<Field>} */
const fields = Comm100API.get('livechat.prechat.fields', campaignId);

Campaign ID is optional parameter that can be used to determine which campaign you would like to
get. If it is not provided, the first campaign ID returned by Comm100API.get('livechat.campaignIds')
will be used as default value.

Here, the API will return a list of fields, each is an object representing the field in form, which
has following structure:

const field = {
  id: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',  // string, unique field id
  value: 'xxx',         // string/File, value of field. File for attachment, string for others.
  label: 'xxx',         // string, label of field
  type: 'xxx',          // string, type of field, all types are listed below
  error: 'xxx',         // string, error message
  isErrorShowed: false, // boolean, whether error is displayed
  isHidden: false,      // boolean, whether field is invisible
  isRequired: false,    // boolean, whether field is required
  isFocused: false,     // boolean, whether field is focused
  options: [            // array, required for fields such as checkbox, radio list, select
    {
      label: 'xxx',     // string, label name
      value: 'xxx',     // string, value
    },
  ],
}

Possible field types are:

• "name": Name field (system field)
• "email": Email field (system field)
• "phone": Phone field (system field)
• "company": Company field (system field)
• "product": Product and Service field (system field)
• "department": Department field (system field)
• "ticket": Ticket field (system field)
• "rating": Rating field (system field)
• "comment": Comment field (system field)
• "subject": Subject field (system field)
• "content": Content field (system field)
• "attachment": Attachment field (system field)
• "text": Text field (custom field)
• "textarea": Textarea field (custom field)
• "radio": Radio Box field (custom field)
• "checkbox": Check Box field (custom field)
• "select": Drop Down List field (custom field)
• "checkbox-list": Check Box List field (custom field)

Set All PreChat Fields

Similar as getting all fields for prechat, you could also use API to set all fields for prechat,
including it's value, error messages, etc.:

/** @type {string} */
const campaignId = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx';
/** @type {Array<Field>} */
const fields = [];
Comm100API.set('livechat.prechat.fields', fields, campaignId);

Campaign ID is optional parameter that can be used to determine which campaign you would like to
get. If it is not provided, the first campaign ID returned by Comm100API.get('livechat.campaignIds')
will be used as default value.

Besides all types of fields listed above, you could also set custom field if system provided
types cannot fulfill all your requirement:

const fields = [{
  id: 'custom',
  type: 'custom', // type of field
  element: function (update, error) {
    const component = document.createElement('input');
    component.onchange = function (event) {
      const value = event.target.value;
      if (value.trim() !== '') {
        error(null);
        update(value);
      } else {
        error('Custom Error Here');
      }
    };
    return component;
  },
}];
Comm100API.set('livechat.prechat.fields', fields);

In example above, a custom field is defined.

The attribute element provides a callback function which will be used to render element. It should
return an HTMLElement which will be placed in form. When callback is triggered, update as a function
will be provided. Custom component should use this update function to inform the system whenever
the value of field has been changed: update(value);.

Also, it provides second param error. This
is also a function, that should be used when you wish to update error of this custom field. Updating
error in this custom field will not make it shown any difference, because yourself have all the
control. However, inform the system that this field has error will prevent default submit action,
so that you can ensure custom will not pass form when custom field is still invalid.
Please be sure to remove error by calling error(null) when field is valid.

Also, please notice that it provides field.id as string in above example. If field id is not
provided as string, this field will not be submitted to server. You can use this to add your own
validation field. However, if you would like the data to be submitted, please add a field id which
matches any existing field id customized in Control Panel, and it must be a string.

Field Change Event

To listen to change event of fields, use following API:

Comm100API.on('livechat.prechat.field.change', function (field) { });

field will be provided when event fires, the structure of this object can be found here.

Blur and Focus

To focus on specific field, use following API:

/** @type {string} */
const fieldId = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx';
Comm100API.do('livechat.prechat.field.focus', fieldId);

To listen to focus/blur event, use one of the following APIs:

Comm100API.on('livechat.prechat.field.focus', function (field) { });
Comm100API.on('livechat.prechat.field.blur', function (field) { });

field will be provided when event fires, the structure of this object can be found here.

Submit Form

Event

When visitor submit prechat form, corresponding event will be triggered. Following API shows how to
listen to this event:

Comm100API.on('livechat.prechat.submit', function (formData) { });

Here, formData is an object containing all values of fields in prechat form. The structure is as
follows:

const formData = {
  name: '', // string, value of name field (i.e. field with type as "name")
  email: '', // string, value of email field (i.e. field with type as "email")
  phone: '', // string, value of phone field (i.e. field with type as "phone")
  company: '', // string, value of company field (i.e. field with type as "company")
  product: '', // string, value of product field (i.e. field with type as "product")
  department: '', // string, id of selected department, '' for not selected
  ticketId: '', // string, value of ticket field (i.e. field with type as "ticket")
  rating: '', // string, value of rating field (i.e. field with type as "rating")
  comment: '', // string, value of comment field (i.e. field with type as "comment")
  subject: '', // string, value of subject field (i.e. field with type as "subject")
  content: '', // string, value of content field (i.e. field with type as "content")
  attachment: File, // File, value of attachment field (i.e. field with type as "attachment")
  custom: { // custom fields, where key is id of the field, and value is field's value
  },
};

Info in formData are all optional and will only be provided if corresponding field is available
in prechat form.

This event will be triggered when visitor submits the form.

When submitting is succeed, following event will be triggered:

Comm100API.on('livechat.prechat.submit.success', function () { });

However, if server reject it, following event will be triggered:

Comm100API.on('livechat.prechat.submit.fail', function (message) { });

where message is a string indicating the error message.

Submit Action

You could also use API to submit prechat form directly:

/** @type {Promise<void>} */
const promise = Comm100API.do('livechat.prechat.submit');

The chat window requires to be opened when submitting the form. Calling this API is equivalent to
clicking the submit button by user. That means, if any of the fields has issue, submit will fail.
Hence, for this API, a promise will be returned, indicating whether submit success or not.
If promise is rejected, a list of IDs will be provided as first parameter, indicating which fields
are invalid due to incorrect values; if first parameter is null, you could check the second
parameter for possible error message.

Display

You could listen to display event of prechat form:

Comm100API.on('livechat.prechat.display', function () { });

Minimize

You could listen to minimize event of prechat form:

Comm100API.on('livechat.prechat.minimize', function () { });

To minimize the form manually, use following API:

Comm100API.do('livechat.prechat.minimize');

Restore

You could listen to restore event of prechat form:

Comm100API.on('livechat.prechat.restore', function () { });

To restore the form manually, use following API:

Comm100API.do('livechat.prechat.restore');

Close

You could listen to close event of prechat form:

Comm100API.on('livechat.prechat.close', function () { });

To close the form manually, use following API:

Comm100API.do('livechat.prechat.close');

Replacement

There are several components in prechat form which can be replaced by your own component, following
are they and how you could replace:

Header Icons

Comm100API.render('livechat.prechat.header.icons', function () {
  // return custom HTMLElement to replace default component
});

Header

Comm100API.render('livechat.prechat.header', function () {
  // return custom HTMLElement to replace default component
});

Greeting Message Area

Comm100API.render('livechat.prechat.greeting', function () {
  // return custom HTMLElement to replace default component
});

Social Login Area

Comm100API.render('livechat.prechat.social', function () {
  // return custom HTMLElement to replace default component
});

Prechat Form

Comm100API.render('livechat.prechat.form', function () {
  // return custom HTMLElement to replace default component
});

Submit Button

Comm100API.render('livechat.prechat.submit', function () {
  // return custom HTMLElement to replace default component
});

Footer

Comm100API.render('livechat.prechat.footer', function () {
  // return custom HTMLElement to replace default component
});

Powered-by Area

Comm100API.render('livechat.prechat.footer.poweredby', function () {
  // return custom HTMLElement to replace default component
});