Содержание документации

Начало работы

Чат-виджет

Входящие и эл. почта

Контакты

База знаний

AI-агенты

Задачи

Файлы

Файлы и папки

Аналитика

Аналитика

Аккаунт и оплата

Вопросы и помощь

JavaScript API чат-виджета

Обновлено 2 ноября 2026 г.

Сайт управляет чат-виджетом через одну функцию HrcWidget: сообщает, кто посетитель, открывает и закрывает окно, слушает события. Каждый вызов выглядит так: HrcWidget('<команда>', ...аргументы).

Загрузка и очередь

Используйте полный код для вставки. Вызовы, сделанные до загрузки загрузчика, ждут в очереди HrcWidget.q и выполняются по порядку, включая функции (callback). Вызовы после загрузчика, но до init, хранятся до 100; при переполнении первым отбрасывается track, никогда identify, reset или on.

Неверное значение или неизвестная команда никогда не выбрасывают ошибку на вашей странице: они пропускаются с одним предупреждением в консоли. debug: true расскажет больше.

Типы TypeScript

Типы со всеми командами: https://widget.hrc.lt/v1/hrc.d.ts. Скачайте файл к своему коду:

// Скачайте в проект:
// https://widget.hrc.lt/v1/hrc.d.ts
/// <reference path="./hrc.d.ts" />

// редактор проверяет типы
HrcWidget('open', { view: 'new', type: 'question' });

init

Запускает виджет. Повторный init с другим ключом выключает старый виджет и запускает новый.

HrcWidget('init', {
  // из вашего кода для вставки
  widgetKey: 'wk_xxxxxxxxxxxxxxxxxxxx',
  // или 'lt', 'en', 'ru', 'pl', ...
  locale: 'auto',
  // работает как update
  profile: { attributes: { plan: 'pro' } },
  context: {
    appVersion: '3.8.1',
    custom: { page_type: 'checkout' },
  },
  // 'hidden' для своей кнопки
  launcher: 'default',
  zIndex: 2147483000,
  // true: выводит отброшенные значения
  debug: false,
});

Параметр	Значение
`widgetKey`	Ключ виджета с вкладки «Установка». Обязателен.
`locale`	`'auto'` или код языка, например `'lt'`.
`identity`	То же, что `identify`.
`profile`	То же, что `update`, применяется, когда у посетителя появляется сессия.
`context`	То же, что `setContext`.
`launcher`	`'default'` или `'hidden'` (кнопка скрыта, `open` работает).
`zIndex`	Слой виджета, по умолчанию 2147483000.
`debug`	`true` объясняет в консоли пропущенные значения.

identify

Распознаёт вошедшего пользователя: он видит свои диалоги на любом устройстве. userHash вычисляется на вашем сервере, смотрите Подтверждение личности. Вместе с ним можно передать поля профиля.

HrcWidget('identify', {
  // ID пользователя, всегда текст
  externalId: String(user.id),
  email: user.email,
  name: user.name,
  // см. «Подтверждение личности»
  userHash: userHashFromYourServer,
  company: { id: 'acme-1', name: 'Acme', plan: 'Pro' },
  attributes: { plan: 'pro', seats: 12, trial_ends_at: '2026-12-01' },
  tags: ['vip'],
});

update

Частично обновляет профиль посетителя: имя, телефон, аватар, компанию и до 50 своих полей. Поля объединяются по одному; null или '' удаляет поле. Вызовы в пределах 500 мс отправляются вместе. Правила и ограничения: Профиль посетителя.

HrcWidget('update', {
  phone: '+370 600 00000',
  company: {
    name: 'Acme',
    website: 'https://acme.example',
    plan: 'Pro',
  },
  // число, да/нет, дата или текст
  attributes: {
    orders: 14,
    newsletter: true,
    signed_up_at: new Date('2024-03-12'),
    app_version: '3.8.1',
    // null или '' удаляет ключ
    coupon: null,
  },
});

setTags

Массив добавляет метки, объект добавляет и удаляет. До 20 меток на контакт, буквы, цифры и дефис.

// добавляет эти метки
HrcWidget('setTags', ['vip', 'beta']);
// добавляет и удаляет
HrcWidget('setTags', { add: ['churn-risk'], remove: ['beta'] });

track

Записывает одно действие посетителя. Команда видит последние 5 на боковой панели и все на странице контакта.

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

setContext

Заменяет значения сессии, которые отправляются с каждым следующим сообщением. В профиле они не сохраняются. До 20 своих ключей, значение до 200 символов.

// Только для следующих сообщений визита
HrcWidget('setContext', {
  appVersion: '3.8.1',
  custom: { cart_id: 'c-1042', step: 'payment' },
});

open, close, toggle и кнопка

open открывает окно: view это 'home', 'new' или 'list', type это 'bug', 'feature' или 'question'. С view: 'new' параметр message вставляет текст в поле нового диалога (не отправляет, до 2000 символов).

// главный экран
HrcWidget('open');
// диалоги посетителя
HrcWidget('open', { view: 'list' });
// сразу форма ошибки
HrcWidget('open', { view: 'new', type: 'bug' });
// текст в поле, не отправлен
HrcWidget('open', { view: 'new', message: 'Order #1042: ' });
HrcWidget('close');
HrcWidget('toggle');
// open() по-прежнему работает
HrcWidget('hideLauncher');
HrcWidget('showLauncher');

on и off: события

function onUnread(event) {
  document.title = event.count ? '(' + event.count + ') Shop' : 'Shop';
}
// сразу с текущим числом
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);
});
// удаляет эту функцию
HrcWidget('off', 'unread', onUnread);
// удаляет все функции ready
HrcWidget('off', 'ready');

Событие	Данные	Когда
`ready`	`{ isIdentified, hasConversations, unreadCount, locale }`	Виджет запущен. Добавленный позже `on('ready')` сразу получает последнее значение.
`open`	`{ view }`	При каждом открытии.
`close`	`{}`	При каждом закрытии.
`unread`	`{ count }`	Сразу с текущим значением, затем при каждом изменении.
`message`	`{ unreadCount }`	Пришёл ответ команды, который посетитель ещё не прочитал. Без текста, чтобы другие скрипты на странице не читали ответы.
`conversation-started`	`{ conversationId, type }`	Посетитель начал диалог.
`identified`	`{}`	`identify` прошёл.
`identify-failed`	`{ code }`	`identify` не прошёл, например `IDENTITY_INVALID`.

Callback, который выбрасывает ошибку, пишет одно предупреждение и не останавливает ни виджет, ни другие callback.

setLocale, reset и destroy

// меняет язык сразу, или 'auto'
HrcWidget('setLocale', 'pl');
// при выходе: забывает посетителя
HrcWidget('reset');
// убирает виджет; затем снова init
HrcWidget('destroy');

reset забывает сессию, распознавание и все ещё не отправленные изменения профиля, метки, действия и значения сессии. Вызывайте его, когда пользователь выходит.

Одностраничные приложения

Смену страницы (pushState, popstate) загрузчик замечает сам, поэтому в сообщениях видна настоящая страница. Пример для React: Код для вставки, React и CSP.

Не нашли ответа? Напишите нам