Javascript API

Contact Identity Verification (Pre-Authentication)

Pre-authentication lets you automatically sign in your logged-in users to the live chat widget, so they don't have to enter their name and email manually.

How it works

1. Your server calls the Herodesk API to generate a secure hash for the contact
2. Your frontend passes the hash (along with the contact's details) to the chat widget
3. The widget verifies the token and signs the contact in automatically

Step 1: Generate the Hash (Server-Side)

Make a GET request to the Herodesk API from your backend:

GET https://api.herodesk.io/v1/contacts/chat-auth-token?email=john@example.com
Authorization: Bearer YOUR_API_KEY

Note: See https://api.herodesk.io/#/Contacts/contacts_chat_auth_token for API details.

Response:
{
  "contact_id": 123,
  "email": "john@example.com",
  "name": "John Doe",
  "auth_token": "a1b2c3d4e5f6..."
}

You can also look up by id instead of email:

GET https://api.herodesk.io/v1/contacts/chat-auth-token?id=123
Authorization: Bearer YOUR_API_KEY

**Important:** Never expose your API key on the frontend. Always generate the auth token on your server.  

Performance: Sessison Caching

The widget automatically caches the contact's identity in browser cookies after the first successful identification. On subsequent page loads (or SPA navigations), if the same email is passed via boot, the widget skips the identify API call entirely and uses the cached session.

How It Works

1. First visit: API is called → cookies are set
2. Subsequent visits: Email hash is compared with cached hash → API call is skipped

Cookie Storage

• herodesk_contact_identified - Hashed email fingerprint (365 days)
• herodesk-chat-contact_uuid - Contact UUID (365 days)
• herodesk_contact_verified - Verification token (365 days)

When API Calls Are Made

1. ✅ First visit (no cookies)
The contact visits for the first time (no cached session)

2. ✅ Email changed (stale cookies cleared)
The email address changes between page loads (stale cookies are cleared automatically)

3. ✅ Cookies expired (browser cleanup)
The cookies have expired or been cleared by the browser

4. ❌ Same email within cookie lifetime → No API Call

Note: This means you can safely call Herodesk('boot', {...}) on every page without worrying about redundant API requests or performance impact.

Javascript API Methods

The Herodesk function provides methods to control the widget programmatically and listen to events. Call these after the widget script has loaded.

State Properties

The Herodesk object exposes read-only state properties that reflect the current widget status:

Example:

// Check if the widget is ready before showing
if (Herodesk.isReady && !Herodesk.isVisible) {
 Herodesk('show');
}

Note: State properties are updated automatically. isVisible syncs with both programmatic calls (show/hide) and user interactions (clicking the launcher icon or close button). 

Herodesk('boot', {});

Use the global Herodesk function to boot the widget with the contact's details. Place this before the Herodesk chat script loads: 

<script>
 // Queue stub — must be placed before the widget script
 // Why do we use Queue stub ? Because the widget never goes through a "first anonymous, 
 // then identified" transition. It starts with the correct identity from the very first frame.
 window.Herodesk = window.Herodesk || function() {
   (window.Herodesk.q = window.Herodesk.q || []).push(arguments);
 };


 // Boot with contact details and auth token from Step 1
 Herodesk('boot', {
   email: "john@example.com",
   firstname: "John",
   lastname: "Doe",
   auth_token: "a1b2c3d4e5f6..."  // auth_token from Step 1
 });
</script>


<!-- Load the Herodesk chat widget AFTER setting HerodeskSettings -->
<script src="https://cdn.herodesk.io/livechat.js?wid=YOUR_WIDGET_ID"></script>

Boot Parameters

* If auth_token is omitted or invalid, the contact will not be verified automatically. They will go through the standard email verification flow instead.

Pre-filling a Message

You can pre-fill the chat input field with pre-authentication:

<script src="https://cdn.herodesk.io/livechat.js?wid=YOUR_WIDGET_ID"></script>
<script>
 Herodesk('boot', {
   email: "john@example.com",
   firstname: "John",
   auth_token: "a1b2c3d4e5f6...",
   message: "I need help with order #12345"
 });
</script>

Custom z-index

<script src="https://cdn.herodesk.io/livechat.js?wid=YOUR_WIDGET_ID"></script>
<script>
 Herodesk('boot', {
   z_index: 500
 });
</script>

Herodesk('show');

Opens the chat widget programmatically.

Herodesk('show');

Herodesk('hide');

Close the chat widget programmatically.

Herodesk('hide');

Herodesk('showConversation', id);

Opens a specific conversation by its ID. The conversation must belong to the current contact.

Herodesk('showConversation', 231);

Note: This method only works after the widget has loaded and the contact has been identified. The conversation ID must belong to the current contact — attempting to open another contact's conversation will be rejected.

Event Callbacks

Register callbacks to respond to widget events.

Herodesk('onShow', callback);

Fires when the chat widget is opened (by user click or programmatic show).

Herodesk('onShow', function() {
 console.log('Chat widget opened');
});

Herodesk('onHide', callback);

Fires when the chat widget is closed (by user click or programmatic hide).

Herodesk('onHide', function() {
 console.log('Chat widget closed');
});

Herodesk('onUnreadCountChange', callback);

Fires when the number of unread conversations changes. Receives the new count as a parameter.

Herodesk('onUnreadCountChange', function(count) {
 console.log('Unread conversations:', count);
});

Herodesk('onUserEmailSupplied', callback);

Fires when a contact's email is identified — either through pre-authentication (boot with auth_token) or when the user manually enters their email in the widget's contact form.

Herodesk('onUserEmailSupplied', function() {
 console.log('User email has been supplied');
});