Documentation contents

Getting started

Chat widget

Inbox and e-mail

Contacts

Knowledge base

AI agents

Tasks

Files

Files and folders

Analytics

Analytics

Account and billing

FAQ and support

Chat widget JavaScript API

Updated November 2, 2026

Your site controls the chat widget through one function, HrcWidget: tell it who the visitor is, open and close the window, listen to events. Every call looks like this: HrcWidget('<command>', ...arguments).

Loading and the queue

Use the full embed code. Calls made before the loader arrives wait in the HrcWidget.q queue and run in order, functions (callbacks) included. Calls made after the loader but before init are kept up to 100; over that a track is dropped first, never identify, reset or on.

A bad value or an unknown command never throws into your page: it is dropped with one console warning. debug: true tells you more.

TypeScript types

The types with every command: https://widget.hrc.lt/v1/hrc.d.ts. Download the file next to your code:

// Download into your project:
// https://widget.hrc.lt/v1/hrc.d.ts
/// <reference path="./hrc.d.ts" />

// checked by your editor
HrcWidget('open', { view: 'new', type: 'question' });

init

Starts the widget. Calling init again with another key tears the old widget down and starts the new one.

HrcWidget('init', {
  // from your embed code
  widgetKey: 'wk_xxxxxxxxxxxxxxxxxxxx',
  // or 'lt', 'en', 'ru', 'pl', ...
  locale: 'auto',
  // applied like update
  profile: { attributes: { plan: 'pro' } },
  context: {
    appVersion: '3.8.1',
    custom: { page_type: 'checkout' },
  },
  // 'hidden' for your own button
  launcher: 'default',
  zIndex: 2147483000,
  // true logs dropped values
  debug: false,
});

Option	Value
`widgetKey`	The widget key from the Install tab. Required.
`locale`	`'auto'` or a language code such as `'lt'`.
`identity`	The same as `identify`.
`profile`	The same as `update`, applied once the visitor has a session.
`context`	The same as `setContext`.
`launcher`	`'default'` or `'hidden'` (the button is hidden, `open` still works).
`zIndex`	The widget's layer, 2147483000 by default.
`debug`	`true` explains dropped values in the console.

identify

Recognizes a signed-in user: they see their conversations on any device. userHash is computed on your server, see Identity verification. You can pass profile fields with it.

HrcWidget('identify', {
  // your user id, always a string
  externalId: String(user.id),
  email: user.email,
  name: user.name,
  // see "Identity verification"
  userHash: userHashFromYourServer,
  company: { id: 'acme-1', name: 'Acme', plan: 'Pro' },
  attributes: { plan: 'pro', seats: 12, trial_ends_at: '2026-12-01' },
  tags: ['vip'],
});

update

A partial update of the visitor profile: name, phone, avatar, company and up to 50 custom fields. Fields merge one by one; null or '' removes a field. Calls within 500 ms go out together. Rules and limits: Visitor profile.

HrcWidget('update', {
  phone: '+370 600 00000',
  company: {
    name: 'Acme',
    website: 'https://acme.example',
    plan: 'Pro',
  },
  // number, boolean, date or string
  attributes: {
    orders: 14,
    newsletter: true,
    signed_up_at: new Date('2024-03-12'),
    app_version: '3.8.1',
    // null or '' removes the key
    coupon: null,
  },
});

setTags

An array adds tags, an object adds and removes them. Up to 20 tags per contact, letters, digits and hyphens.

// adds these tags
HrcWidget('setTags', ['vip', 'beta']);
// adds and removes
HrcWidget('setTags', { add: ['churn-risk'], remove: ['beta'] });

track

Records one thing the visitor did. Your team sees the newest 5 in the sidebar and all of them on the contact page.

HrcWidget('track', 'plan-upgraded', { from: 'free', to: 'pro' });
HrcWidget('track', 'checkout.failed', {
  reason: 'card_declined',
  amount: 49.9,
});

setContext

Replaces the session values sent with every next message. They are not stored on the profile. Up to 20 custom keys, values up to 200 characters.

// Only for this visit's next messages
HrcWidget('setContext', {
  appVersion: '3.8.1',
  custom: { cart_id: 'c-1042', step: 'payment' },
});

open, close, toggle and the launcher

open opens the window: view is 'home', 'new' or 'list', type is 'bug', 'feature' or 'question'. With view: 'new', the message option puts text in the new conversation's composer (not sent, up to 2000 characters).

// the home view
HrcWidget('open');
// the visitor's conversations
HrcWidget('open', { view: 'list' });
// straight to the bug form
HrcWidget('open', { view: 'new', type: 'bug' });
// text in the composer, not sent
HrcWidget('open', { view: 'new', message: 'Order #1042: ' });
HrcWidget('close');
HrcWidget('toggle');
// open() still works
HrcWidget('hideLauncher');
HrcWidget('showLauncher');

on and off: events

function onUnread(event) {
  document.title = event.count ? '(' + event.count + ') Shop' : 'Shop';
}
// fires at once with the current count
HrcWidget('on', 'unread', onUnread);
HrcWidget('on', 'ready', function (event) {
  console.log(event.isIdentified, event.locale);
});
HrcWidget('on', 'conversation-started', function (event) {
  console.log(event.type);
});
// removes this callback
HrcWidget('off', 'unread', onUnread);
// removes every ready callback
HrcWidget('off', 'ready');

Event	Payload	When
`ready`	`{ isIdentified, hasConversations, unreadCount, locale }`	The widget started. An `on('ready')` added later gets the last value at once.
`open`	`{ view }`	Every open.
`close`	`{}`	Every close.
`unread`	`{ count }`	At once with the current value, then on every change.
`message`	`{ unreadCount }`	A team reply arrived that the visitor has not read. No text, so other scripts on the page cannot read replies.
`conversation-started`	`{ conversationId, type }`	The visitor started a conversation.
`identified`	`{}`	`identify` succeeded.
`identify-failed`	`{ code }`	`identify` failed, for example `IDENTITY_INVALID`.

A callback that throws logs one warning and never stops the widget or the other callbacks.

setLocale, reset and destroy

// switch the language now, or 'auto'
HrcWidget('setLocale', 'pl');
// on logout: forgets the visitor
HrcWidget('reset');
// removes the widget; call init again
HrcWidget('destroy');

reset forgets the session, the identity and every profile change, tag, event and session value not sent yet. Call it when the user signs out.

Single page apps

The loader notices route changes (pushState, popstate) by itself, so messages carry the real page. React example: Embed code, React and CSP.

Did not find the answer? Write to us