Перейти до вмісту
HRC pagalba
UAУкраїнська
Увійти
Зміст документації

Початок роботи

Чат-віджет

Вхідні й ел. пошта

Контакти

База знань

AI-агенти

Завдання

Файли

Аналітика

Обліковий запис і оплата

Питання й допомога

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

Оновлено

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

Завантаження й черга

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

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

Типи TypeScript

Типи з усіма командами: https://widget.hrc.lt/v1/hrc.d.ts. Завантажте файл до свого коду:

ts
// Завантажте у проєкт:
// https://widget.hrc.lt/v1/hrc.d.ts
/// <reference path="./hrc.d.ts" />

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

init

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

js
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 обчислюється на вашому сервері, дивіться Підтвердження особи. Разом із ним можна передати поля профілю.

js
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 мс надсилаються разом. Правила й обмеження: Профіль відвідувача.

js
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 міток на контакт, літери, цифри й дефіс.

js
// додає ці мітки
HrcWidget('setTags', ['vip', 'beta']);
// додає й видаляє
HrcWidget('setTags', { add: ['churn-risk'], remove: ['beta'] });

track

Записує одну дію відвідувача. Команда бачить останні 5 на бічній панелі й усі на сторінці контакту.

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

setContext

Замінює значення сесії, які надсилаються з кожним наступним повідомленням. У профілі вони не зберігаються. До 20 власних ключів, значення до 200 символів.

js
// Лише для наступних повідомлень візиту
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 символів).

js
// головний екран
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: події

js
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

js
// змінює мову одразу, або 'auto'
HrcWidget('setLocale', 'pl');
// при виході: забуває відвідувача
HrcWidget('reset');
// прибирає віджет; потім знову init
HrcWidget('destroy');

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

Односторінкові застосунки

Зміну сторінки (pushState, popstate) завантажувач помічає сам, тож у повідомленнях видно справжню сторінку. Приклад для React: Код для вставлення, React і CSP.

Не знайшли відповіді? Напишіть нам