Chat Widget SDK Reference

FrontChat('init', options)

By default, the chat launcher will become visible immediately after the page loads. This is not always desirable if you want to use an alternative button or delay when the chat becomes available. If you don't call the init method, useDefaultLauncher will be true by default.

Note: You can only call init once per page load.

 FrontChat('init', {
    useDefaultLauncher: false // optional

Init with verified identity

You can optionally pass the identity of the user in the init call.

  FrontChat('init', {
    useDefaultLauncher: false,
    email: '[email protected]',
    userHash: '<generated using the verification secret>',
    name: 'Turanga Leela',
    customFields: { 'Packages delivered': 242 }


You can use shutdown to remove the chat from your page after starting it. The chat will disappear from the page until init is called again (or the page is reloaded).



This will open the main FrontChat messenger panel.



This will close the main FrontChat messenger panel. If useDefaultLancher was set to false, the launcher will not appear.


FrontChat('onUnreadChange', handler)

This method allows you to register a function (the handler) that will be called when the current number of unread messages changes. The handler is expected to be a function that will receive an object like {unread_count: 1} as its first parameter. The handler will always be called immediately to pass an initial value.

It will return an unbind function that you can call to unregister the handler.

const unbind = FrontChat('onUnreadChange', handler);

FrontChat('identity', object)

This method allows you to pass an identity object to Front in order for the user to be identified when they send messages. The object can take the following shape:

FrontChat('identity', {
  email: '[email protected]',
  name: 'Turanga Leela',
  userHash: '<generated using the verification secret>',
  customFields: {
    'Shipments delivered': 242,
    Title: 'Parcel Captain',
    'Is admin': true

All fields are optional (though userHash never needs to be passed if email is not provided). The custom fields are defined by the custom fields for contacts that you have created in Front.

Note: if the user provides their name or email it will override what is provided in the identity information.

Identity verification

The mandatory user hash guarantees that users are who they claim to be. Otherwise, a user could manually run Javascript commands to impersonate another one and view their conversations.

You can configure Front Chat to accept both anonymous and identified users. You can also completely disable anonymous users to avoid any confusion.

The value of the email field should be a valid email address. This value is used in Front to associate a new or existing contact with a conversation they have started via Chat:


Computing the user hash

Front Chat uses a server-side generated HMAC (hash based message authentication code) with SHA-256. The identity verification will fail unless a user hash is provided.

// computing a user hash based on HMAC-SHA256
// Node.js example
const crypto = require('crypto');
const hmac = crypto.createHmac('sha256', verificationSecret);
const userHash = hmac.update(userEmail).digest('hex');
// computing a user hash based on HMAC-SHA256
// PHP example
$userHash = hash_hmac('sha256', $userEmail, $verificationSecret);
// computing a user hash based on HMAC-SHA256
// Ruby example
require 'openssl'
userHash = OpenSSL::HMAC.hexdigest('sha256'), verificationSecret, userEmail)
import hashlib
import hmac, msg=user_email.encode('utf8'), digestmod=hashlib.sha256).hexdigest()

To compute a user hash, you will first need to retrieve your identity secret, which is available in your Front settings. Go to Settings > Inboxes > (Your chat inbox) > (Your chat channel) and expand the section "Verify logged-in user identity":


Important: the verification secret must remain private and must not appear in your frontend source code. The user hash must be computed in your backend, without disclosing the secret.

Did this page help you?