# JavaScript API чат-віджета > Усі команди JavaScript API чат-віджета: init, identify, update, setTags, track, setContext, open, on і off, reset і destroy, з прикладами. Сайт керує чат-віджетом через одну функцію `HrcWidget`: повідомляє, хто відвідувач, відкриває й закриває вікно, слухає події. Кожен виклик виглядає так: `HrcWidget('<команда>', ...аргументи)`. ## Завантаження й черга Використовуйте [повний код для вставлення](https://hrc.lt/uk/docs/widget/install). Виклики, зроблені до завантаження завантажувача, чекають у черзі `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). Завантажте файл до свого коду: ```ts // Завантажте у проєкт: // https://widget.hrc.lt/v1/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` обчислюється на вашому сервері, дивіться [Підтвердження особи](https://hrc.lt/uk/docs/widget/identity-verification). Разом із ним можна передати поля профілю. ```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 мс надсилаються разом. Правила й обмеження: [Профіль відвідувача](https://hrc.lt/uk/docs/widget/visitor-profile). ```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](https://hrc.lt/uk/docs/widget/install).