# JavaScript API чат-виджета > Все команды JavaScript API чат-виджета: init, identify, update, setTags, track, setContext, open, on и off, reset и destroy, с примерами. Сайт управляет чат-виджетом через одну функцию `HrcWidget`: сообщает, кто посетитель, открывает и закрывает окно, слушает события. Каждый вызов выглядит так: `HrcWidget('<команда>', ...аргументы)`. ## Загрузка и очередь Используйте [полный код для вставки](https://hrc.lt/ru/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/ru/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/ru/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/ru/docs/widget/install).