Spis dokumentacji

Pierwsze kroki

Widżet czatu

Skrzynka i e-mail

Kontakty

Baza wiedzy

Agenci AI

Zadania

Pliki

Pliki i foldery

Analityka

Analityka

Konto i płatności

FAQ i pomoc

API JavaScript widżetu czatu

Zaktualizowano 2 listopada 2026

Strona steruje widżetem czatu przez jedną funkcję HrcWidget: mówi, kim jest odwiedzający, otwiera i zamyka okno, nasłuchuje zdarzeń. Każde wywołanie wygląda tak: HrcWidget('<polecenie>', ...argumenty).

Ładowanie i kolejka

Użyj pełnego kodu do osadzenia. Wywołania sprzed pobrania skryptu ładującego czekają w kolejce HrcWidget.q i wykonują się po kolei, razem z funkcjami (callback). Wywołania po skrypcie ładującym, ale przed init, są przechowywane do 100; po przepełnieniu najpierw odrzucany jest track, nigdy identify, reset ani on.

Zła wartość lub nieznane polecenie nigdy nie rzuca błędu na twojej stronie: zostaje pominięte z jednym ostrzeżeniem w konsoli. debug: true powie więcej.

Typy TypeScript

Typy ze wszystkimi poleceniami: https://widget.hrc.lt/v1/hrc.d.ts. Pobierz plik do swojego kodu:

// Pobierz do projektu:
// https://widget.hrc.lt/v1/hrc.d.ts
/// <reference path="./hrc.d.ts" />

// edytor sprawdza typy
HrcWidget('open', { view: 'new', type: 'question' });

init

Uruchamia widżet. Ponowne init z innym kluczem wyłącza stary widżet i uruchamia nowy.

HrcWidget('init', {
  // z twojego kodu do osadzenia
  widgetKey: 'wk_xxxxxxxxxxxxxxxxxxxx',
  // lub 'lt', 'en', 'ru', 'pl', ...
  locale: 'auto',
  // działa jak update
  profile: { attributes: { plan: 'pro' } },
  context: {
    appVersion: '3.8.1',
    custom: { page_type: 'checkout' },
  },
  // 'hidden' dla własnego przycisku
  launcher: 'default',
  zIndex: 2147483000,
  // true: loguje odrzucone wartości
  debug: false,
});

Opcja	Wartość
`widgetKey`	Klucz widżetu z karty „Instalacja”. Wymagany.
`locale`	`'auto'` albo kod języka, np. `'lt'`.
`identity`	To samo co `identify`.
`profile`	To samo co `update`, stosowane, gdy odwiedzający ma sesję.
`context`	To samo co `setContext`.
`launcher`	`'default'` albo `'hidden'` (przycisk ukryty, `open` działa).
`zIndex`	Warstwa widżetu, domyślnie 2147483000.
`debug`	`true` wyjaśnia w konsoli pominięte wartości.

identify

Rozpoznaje zalogowanego użytkownika: widzi on swoje rozmowy na każdym urządzeniu. userHash liczy twój serwer, zobacz Weryfikacja tożsamości. Razem z nim możesz przekazać pola profilu.

HrcWidget('identify', {
  // ID użytkownika, zawsze tekst
  externalId: String(user.id),
  email: user.email,
  name: user.name,
  // zob. „Weryfikacja tożsamości”
  userHash: userHashFromYourServer,
  company: { id: 'acme-1', name: 'Acme', plan: 'Pro' },
  attributes: { plan: 'pro', seats: 12, trial_ends_at: '2026-12-01' },
  tags: ['vip'],
});

update

Częściowo aktualizuje profil odwiedzającego: imię, telefon, awatar, firmę i do 50 własnych pól. Pola łączą się po jednym; null lub '' usuwa pole. Wywołania w ciągu 500 ms idą razem. Zasady i limity: Profil odwiedzającego.

HrcWidget('update', {
  phone: '+370 600 00000',
  company: {
    name: 'Acme',
    website: 'https://acme.example',
    plan: 'Pro',
  },
  // liczba, tak/nie, data lub tekst
  attributes: {
    orders: 14,
    newsletter: true,
    signed_up_at: new Date('2024-03-12'),
    app_version: '3.8.1',
    // null lub '' usuwa klucz
    coupon: null,
  },
});

setTags

Tablica dodaje tagi, obiekt dodaje i usuwa. Do 20 tagów na kontakt, litery, cyfry i myślnik.

// dodaje te tagi
HrcWidget('setTags', ['vip', 'beta']);
// dodaje i usuwa
HrcWidget('setTags', { add: ['churn-risk'], remove: ['beta'] });

track

Zapisuje jedno działanie odwiedzającego. Zespół widzi 5 najnowszych na pasku bocznym, a wszystkie na stronie kontaktu.

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

setContext

Zastępuje wartości sesji wysyłane z każdą kolejną wiadomością. Nie są zapisywane w profilu. Do 20 własnych kluczy, wartość do 200 znaków.

// Tylko dla kolejnych wiadomości wizyty
HrcWidget('setContext', {
  appVersion: '3.8.1',
  custom: { cart_id: 'c-1042', step: 'payment' },
});

open, close, toggle i przycisk

open otwiera okno: view to 'home', 'new' lub 'list', type to 'bug', 'feature' lub 'question'. Z view: 'new' opcja message wpisuje tekst w pole nowej rozmowy (nie wysyła, do 2000 znaków).

// ekran startowy
HrcWidget('open');
// rozmowy odwiedzającego
HrcWidget('open', { view: 'list' });
// od razu formularz błędu
HrcWidget('open', { view: 'new', type: 'bug' });
// tekst w polu, niewysłany
HrcWidget('open', { view: 'new', message: 'Order #1042: ' });
HrcWidget('close');
HrcWidget('toggle');
// open() nadal działa
HrcWidget('hideLauncher');
HrcWidget('showLauncher');

on i off: zdarzenia

function onUnread(event) {
  document.title = event.count ? '(' + event.count + ') Shop' : 'Shop';
}
// od razu z bieżącą liczbą
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);
});
// usuwa tę funkcję
HrcWidget('off', 'unread', onUnread);
// usuwa wszystkie funkcje ready
HrcWidget('off', 'ready');

Zdarzenie	Dane	Kiedy
`ready`	`{ isIdentified, hasConversations, unreadCount, locale }`	Widżet wystartował. Dodane później `on('ready')` od razu dostaje ostatnią wartość.
`open`	`{ view }`	Przy każdym otwarciu.
`close`	`{}`	Przy każdym zamknięciu.
`unread`	`{ count }`	Od razu z bieżącą wartością, potem przy każdej zmianie.
`message`	`{ unreadCount }`	Przyszła odpowiedź zespołu, której odwiedzający jeszcze nie przeczytał. Bez tekstu, by inne skrypty na stronie nie czytały odpowiedzi.
`conversation-started`	`{ conversationId, type }`	Odwiedzający rozpoczął rozmowę.
`identified`	`{}`	`identify` się powiodło.
`identify-failed`	`{ code }`	`identify` się nie powiodło, np. `IDENTITY_INVALID`.

Callback, który rzuca błąd, zapisuje jedno ostrzeżenie i nie zatrzymuje ani widżetu, ani innych callbacków.

setLocale, reset i destroy

// zmienia język od razu, albo 'auto'
HrcWidget('setLocale', 'pl');
// wylogowanie: zapomina odwiedzającego
HrcWidget('reset');
// usuwa widżet; potem znów init
HrcWidget('destroy');

reset zapomina sesję, rozpoznanie oraz wszystkie jeszcze niewysłane zmiany profilu, tagi, działania i wartości sesji. Wywołuj go, gdy użytkownik się wylogowuje.

Aplikacje jednostronicowe

Zmianę strony (pushState, popstate) skrypt ładujący wykrywa sam, więc w wiadomościach widać prawdziwą stronę. Przykład dla React: Kod do osadzenia, React i CSP.

Nie ma tu odpowiedzi? Napisz do nas