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 }

FrontChat('shutdown', options)

You can use shutdown to remove the chat widget from your page after starting it. The chat widget will disappear from the page until init is called again (or the page is reloaded). If the chat widget is reinitialized later, the previous conversation will be resumed.


Shutdown and clear session

When calling shutdown, you can optionally clear the existing chat session. This will remove the Front Chat cookies associated with the chat session and clear any previously supplied identity information. Any initialization call after clearing the session will begin a fresh conversation.

 FrontChat('shutdown', {clearSession: true});


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.

Accessing chat messages through the Core API

Like all communication channels in Front, messages sent and received through Front Chat can be accessed through the Core API . The Message object for Front Chat messages also includes a metadata.chat_visitor_url property that denotes the URL that the chat visitor was on when they sent the message. Front Chat messages sent by Front users do not contain this property.