Konradodocs

Weryfikacja tożsamości

Przekaż czatowi, który zalogowany klient pisze, aby Konrado mógł odpowiadać o jego własnym koncie.

Po wykonaniu kroków z tej strony czat wie, który zalogowany klient pisze. Konrado może wtedy przeczytać jego usługi, faktury, zgłoszenia i konfigurację hostingu, zamiast pytać, kim jest.

Jak to działa

Twój serwer przy każdym wyświetleniu strony podpisuje krótki token dla zalogowanego klienta i umieszcza go w kodzie czatu. Czat przekazuje token Konrado jeden raz. Konrado sprawdza podpis kluczem tajnym z konsoli i przypisuje rozmowę do tego klienta. Brak tokenu albo token wygasły lub błędny daje zwykły anonimowy czat, nigdy błąd.

Klucz znają tylko Twój serwer i Konrado, więc nic w przeglądarce nie może podrobić klienta.

Zanim zaczniesz

  • Czat jest zainstalowany na stronie, na której klienci się logują.
  • Możesz uruchomić kod na serwerze, który generuje stronę. Konsola przygotowuje go dla Node.js, PHP i strefy klienta WHMCS. Sprawdzi się też każdy język z biblioteką JWT obsługującą HS256. W WordPressie token podpisuje za Ciebie wtyczka Konrado.
  • Podłączony helpdesk. ID, które podpisujesz, to ID klienta w tym helpdesku. Gdy SupportPal jest połączony z WHMCS, podpisz ID klienta WHMCS albo ID z SupportPal z polem platform ustawionym na supportpal. Bez helpdesku Konrado poznaje imię i nazwisko, e-mail i ID z tokenu, ale nie ma konta, którego by dotyczyły.

Kroki

Wygeneruj klucz tajny

Otwórz AgenciCzat na stronieInstalacja i pod krokami instalacji rozwiń sekcję Weryfikacja tożsamości. Kliknij Wygeneruj klucz tajny. Wygenerowanie klucza włącza weryfikację tożsamości, a jego usunięcie ją wyłącza.

Sekcja Weryfikacja tożsamości: zamaskowany klucz tajny z przyciskami Pokaż i Kopiuj klucz tajny, data ostatniej wymiany i ostrzeżenie, by traktować klucz jak hasło

Klucz ma 43 znaki i jest wyświetlany zamaskowany, z widocznymi ostatnimi 4 znakami. Przycisk z okiem, Pokaż, odsłania go. Przycisk kopiowania, Kopiuj klucz tajny, kopiuje go. Menu obok klucza (trzy kropki) zawiera opcje Wymień i Usuń.

Traktuj klucz jak hasło. Każdy, kto go ma, może podszyć się pod Twoich klientów wobec agenta. Trzymaj go tylko na swoim serwerze, nigdy w repozytorium ani w kodzie działającym w przeglądarce.

Podpisz token na swoim serwerze

Przy każdym wyświetleniu strony, gdy klient jest zalogowany, podpisz token JWT z poniższymi polami, używając klucza tajnego. Algorytm to HS256. Kluczem jest sekret dokładnie w takiej postaci, w jakiej jest zapisany, bez dekodowania.

PoleWymaganeWartość
subTakID klienta w Twoim helpdesku albo ID klienta WHMCS, gdy SupportPal jest połączony z WHMCS, chyba że platform wskazuje inaczej. Ciąg znaków o długości do 256 znaków. Wyślij "1234", a nie liczbę 1234: liczba jest odrzucana
iatTakBieżący czas w pełnych sekundach. Ułamek jest odrzucany
expTakMoment, w którym token przestaje działać, w pełnych sekundach. Przykłady używają bieżącego czasu + 300: czat wykorzystuje token w ciągu kilku sekund od załadowania strony
jtiTakLosowy ciąg znaków, nowy przy każdym wyświetleniu. Konrado przyjmuje każdy jti tylko raz
emailNieWidoczny dla agenta, do 320 znaków. Gdy go nie ma, pomiń pole albo wyślij null
nameNieWidoczne dla agenta, do 256 znaków. Gdy go nie ma, pomiń pole albo wyślij null
platformNieSystem, z którego pochodzi sub: whmcs albo supportpal, gdy jeden czat działa na stronach WHMCS i na stronach SupportPal. Bez tego pola Konrado traktuje sub jako ID klienta WHMCS, gdy SupportPal jest połączony z WHMCS, a w przeciwnym razie jako ID w Twoim helpdesku. Z wartością supportpal traktuje sub jako klienta SupportPal i znajduje klienta WHMCS po adresie e-mail. Jeśli pole wskazuje system, z którym ten czat nie jest połączony, Konrado nie czyta żadnego konta. Do 64 znaków. Hook WHMCS wysyła whmcs. W przykładach dla Node.js i PHP ta linia jest zakomentowana

Podpisuj dokładnie to ID, nigdy ID z innego systemu, na przykład ID użytkownika w Twoim sklepie. Konrado czyta konto o podpisanym ID, więc błędne ID może pokazać agentowi konto innego klienta.

Konsola przygotowuje kod za Ciebie. Wybierz platformę w sekcji Wybierz platformę i kliknij Kopiuj. Na zakładkach PHP i WHMCS kopia zawiera Twój prawdziwy klucz, choć na ekranie jest on zamaskowany. Trzymaj więc skopiowany plik poza repozytorium.

Korzysta z pakietu jsonwebtoken. Umieść klucz w zmiennej środowiskowej AI_AGENT_IDENTITY_SECRET, nigdy w kodzie.

// SERVER - runs on your backend, so the secret never reaches the browser.
const jwt = require('jsonwebtoken');
const crypto = require('crypto');

function konradoIdentityToken(user) {
  const now = Math.floor(Date.now() / 1000);

  return jwt.sign(
    {
      sub: String(user.id),           // your id for this customer
      email: user.email ?? undefined, // optional, shown to the agent
      name: user.name ?? undefined,   // optional, shown to the agent
      // platform: 'supportpal',      // optional: the connected system this id is from
      iat: now,                       // required
      exp: now + 300,                 // 5 minutes - the chat redeems it on page load
      jti: crypto.randomUUID(),
    },
    process.env.AI_AGENT_IDENTITY_SECRET,
    { algorithm: 'HS256' },
  );
}

app.get('/*', (req, res) => {
  // Sign on every page render - the token is short-lived by design.
  res.render('page', { token: req.user ? konradoIdentityToken(req.user) : '' });
});

// TEMPLATE - signed-out visitors render the same tag with an empty token attribute,
// which the loader treats as anonymous.
<script async src="https://app.konrado.ai/website-chat/v1/loader.js"
        data-konrado-chat-id="wgt_9808d383733f4e62925c14e2e876eb3a"
        data-konrado-user-token="{{ token }}"></script>

Jeden blok dla dowolnej strony w PHP, wklejany tuż przed </body>. Bez pakietu Composer. Zamień $_SESSION['user'] na sposób, w jaki Twoja aplikacja udostępnia zalogowanego użytkownika.

<?php
/**
 * Konrado.ai chat - paste this block into your page template,
 * just before the closing </body> tag.
 */

// Your Konrado Chat signing key goes here - the dashboard's Copy button fills it in.
// Leave it empty to embed the chat anonymously.
if (!defined('KONRADO_IDENTITY_SECRET')) {
    define('KONRADO_IDENTITY_SECRET', '');
}

// Your signed-in user - swap this for however your app exposes the current user.
// Leave it null for visitors who aren't logged in: they get the same chat, anonymously.
$konradoUser = $_SESSION['user'] ?? null;

$konradoToken = '';

if (KONRADO_IDENTITY_SECRET !== '' && !empty($konradoUser['id'])) {
    $konradoNow = time();
    $konradoClaims = array_filter([
        'sub'   => (string) $konradoUser['id'],   // your id for this customer
        'email' => $konradoUser['email'] ?? null, // optional, shown to the agent
        'name'  => $konradoUser['name'] ?? null,  // optional, shown to the agent
        // 'platform' => 'supportpal',            // optional: the connected system this id is from
        'iat'   => $konradoNow,                   // required
        'exp'   => $konradoNow + 300,             // 5 min - redeemed on page load
        'jti'   => bin2hex(random_bytes(16)),     // random per render - single-use
    ], static function ($value) {
        return $value !== null;
    });

    // Minimal HS256 JWT signer - no Composer dependency needed. A closure rather than a
    // named function so pasting this block into more than one template can't fatal on a
    // duplicate declaration.
    $konradoEncode = static function ($part) {
        return rtrim(strtr(base64_encode(json_encode($part)), '+/', '-_'), '=');
    };
    $konradoPayload = $konradoEncode(['alg' => 'HS256', 'typ' => 'JWT'])
        . '.' . $konradoEncode($konradoClaims);
    $konradoToken = $konradoPayload . '.' . rtrim(strtr(base64_encode(
        hash_hmac('sha256', $konradoPayload, KONRADO_IDENTITY_SECRET, true)
    ), '+/', '-_'), '=');
}
?>
<script async src="https://app.konrado.ai/website-chat/v1/loader.js"
        data-konrado-chat-id="wgt_9808d383733f4e62925c14e2e876eb3a"
        data-konrado-user-token="<?= htmlspecialchars($konradoToken, ENT_QUOTES) ?>"></script>

Plik hooka zapisany jako includes/hooks/konrado_chat.php. WHMCS wczytuje go sam i wyświetla tag w strefie klienta. Zalogowany klient dostaje podpisany token ze swoim ID klienta WHMCS. Wszyscy pozostali dostają zwykły tag.

<?php
/**
 * Konrado.ai chat for the WHMCS client area.
 * Upload this file to /includes/hooks/ - WHMCS picks it up automatically.
 */

if (!defined('WHMCS')) {
    die('This file cannot be accessed directly');
}

// Your Konrado Chat signing key goes here - the dashboard's Copy button fills it in.
// Leave it empty to embed the chat anonymously.
define('KONRADO_IDENTITY_SECRET', '');

add_hook('ClientAreaFooterOutput', 1, function (array $vars) {
    $client = $vars['clientsdetails'] ?? [];

    // Signed-out visitors - and installs with no key yet - get the plain tag. Same
    // install, no second snippet.
    if (KONRADO_IDENTITY_SECRET === '' || empty($client['id'])) {
        return '<script async src="https://app.konrado.ai/website-chat/v1/loader.js"
        data-konrado-chat-id="wgt_9808d383733f4e62925c14e2e876eb3a"></script>';
    }

    $now = time();
    $name = trim(($client['firstname'] ?? '') . ' ' . ($client['lastname'] ?? ''));
    $token = konrado_identity_token([
        'sub'   => (string) $client['id'],   // your id for this customer
        'email' => $client['email'] ?? null, // optional, shown to the agent
        'name'  => $name !== '' ? $name : null, // optional, shown to the agent
        'platform' => 'whmcs',               // the system this id belongs to
        'iat'   => $now,                     // required
        'exp'   => $now + 300,               // 5 min - redeemed on page load
        'jti'   => bin2hex(random_bytes(16)),
    ]);

    return str_replace('{{ token }}', htmlspecialchars($token, ENT_QUOTES), '<script async src="https://app.konrado.ai/website-chat/v1/loader.js"
        data-konrado-chat-id="wgt_9808d383733f4e62925c14e2e876eb3a"
        data-konrado-user-token="{{ token }}"></script>');
});

if (!function_exists('konrado_identity_token')) {
    /** Minimal HS256 JWT signer - no Composer dependency needed. */
    function konrado_identity_token(array $claims): string
    {
        $encode = static function ($part) {
            return rtrim(strtr(base64_encode(json_encode($part)), '+/', '-_'), '=');
        };

        $payload = $encode(['alg' => 'HS256', 'typ' => 'JWT'])
            . '.' . $encode(array_filter($claims, static function ($value) {
                return $value !== null;
            }));
        $signature = hash_hmac('sha256', $payload, KONRADO_IDENTITY_SECRET, true);

        return $payload . '.' . rtrim(strtr(base64_encode($signature), '+/', '-_'), '=');
    }
}

Bez kodu. W WordPressie otwórz SettingsKonrado AI, zaznacz Recognize customers who are logged in to WordPress i wklej klucz w pole Signing secret. Wtyczka podpisuje token dla każdego zalogowanego użytkownika. Domyślnie wysyła jako sub przedrostek wp: i ID użytkownika WordPressa. Takie ID nie pasuje do żadnego klienta w helpdesku, więc agent zna imię i nazwisko oraz e-mail, ale nie konto. Strona Skonfiguruj wtyczkę WordPress pokazuje, jak przypisać użytkownika do klienta w helpdesku.

Umieść token w tagu

Tag przekazuje token w atrybucie data-konrado-user-token. Czat odczytuje go raz, przy ładowaniu strony, i nigdy nie umieszcza go w adresie URL. Dla niezalogowanego odwiedzającego wyświetl tag z pustym atrybutem albo bez tego atrybutu: w obu przypadkach czat jest anonimowy.

Sprawdź, czy działa

Zaloguj się na swojej stronie jako testowy klient, otwórz czat i zapytaj "na jakim jestem planie". Konrado podaje nazwę usługi. Na stronie Skrzynka szczegóły rozmowy pokazują imię i nazwisko klienta, jego e-mail z oznaczeniem zalogowany oraz pole Klient # z jego ID i linkiem do Twojego helpdesku.

Co się zmienia dla zweryfikowanego odwiedzającego

CoAnonimowy odwiedzającyZweryfikowany odwiedzający
Kogo widzi agentNikogo, dopóki odwiedzający sam się nie przedstawiImię i nazwisko, e-mail i ID klienta. Agent może przywitać go po imieniu
Dane kontaBrakUsługi, faktury, zgłoszenia i profil klienta, tylko do odczytu. W SupportPal zgłoszenia i profil. Gdy SupportPal jest połączony z WHMCS, usługi i faktury pochodzą z WHMCS. Klient WHMCS bez konta klienta w SupportPal dostaje tylko te dwie rzeczy: bez zgłoszeń, profilu i własnej usługi
Jego własna usługaBrakGdy podłączona jest integracja serwerowa, Konrado czyta własną usługę klienta na Twoim serwerze, tylko do odczytu: wersję PHP, ustawienia strony i domeny, konta e-mail, bazy danych, zajęte miejsce na dysku, kopie zapasowe i logi błędów. Uruchamia też dla tej usługi każdy test z sekcji Diagnostyka hostingu, w tym cztery oznaczone jako Tylko zalogowani odwiedzający, nawet gdy ta akcja jest wyłączona
Formularz leadaProponowany, gdy warto wrócić do odwiedzającegoNigdy. Klient to nie lead
Zgłoszenie eskalacjiZakładane na e-mail wpisany przez odwiedzającegoZakładane na własnym koncie klienta, z wypełnionym imieniem i nazwiskiem oraz e-mailem. Dostępne są działy oznaczone jako Zalogowani
WyzwalaczeWszystkie grupy odbiorców poza jednąTakże wyzwalacze skierowane do grupy Zalogowani klienci
Na stronie SkrzynkaZwykły awatarZnacznik na awatarze, oznaczenie zalogowany obok e-maila, pole Klient # z linkiem do helpdesku oraz filtr Zalogowany

Wylogowanie i zmiana klienta

Przy każdym ładowaniu strony czat porównuje token z sesją, którą ma już w tej zakładce przeglądarki. Brak pola platform liczy się jako osobna wartość. Dla czatu token z sub: "5", platform: "whmcs" i token z sub: "5" bez platform to więc dwóch różnych klientów.

Strona wyświetlaCo robi czat
Brak tokenu, po wylogowaniuKończy sesję zalogowanego klienta i zaczyna nową anonimową rozmowę
Token z innym sub albo inną wartością platformZaczyna nową sesję i nową rozmowę
Token z tym samym sub i tą samą wartością platformZachowuje sesję. Token nie jest wykorzystywany ponownie, więc powtórzony jti nie jest tu problemem
Token tam, gdzie wcześniej go nie byłoZmienia sesję na zweryfikowaną. Rozmowa trwa dalej, już ze zweryfikowanym klientem

Z helpdeskiem lub bez niego następna osoba w tej samej przeglądarce nie może otworzyć rozmów poprzedniego klienta. Gdy ten klient zaloguje się ponownie, jego rozmowy wracają w sekcji Ostatnie rozmowy. Rozmowa sprzed 13 października 2026 r., której klient nie miał konta w helpdesku, zostaje przy przeglądarce, dopóki ten klient nie napisze w niej ponownie jako zalogowany. Sesja czatu trwa w zakładce 3 godziny.

Wymiana i usunięcie klucza

  • Wymień od razu generuje nowy klucz. Poprzedni klucz działa do następnej wymiany, więc wdróż nowy klucz, zanim wymienisz go ponownie. Jeśli stary klucz mógł wyciec, wdróż nowy klucz, wymień go jeszcze raz i wdróż też ten kolejny: klucz, który wyciekł, przestaje działać przy drugiej wymianie.
  • Usuń wyłącza weryfikację tożsamości. Nowe sesje są anonimowe i nie czytają danych konta. Sesja zweryfikowana wcześniej zachowuje swojego klienta do końca, maksymalnie 3 godziny.

Czego Konrado nie potrafi

Nie da sięDlaczego
Zweryfikować klienta przy samym fragmencie HTMLTag nie potrafi niczego podpisać. Do podpisu potrzebny jest Twój serwer albo wtyczka WordPress
Zgłosić błędnego tokenuBłędny lub wygasły token daje anonimowy czat, bez komunikatu o błędzie dla odwiedzającego ani w konsoli. Zamiast tego sprawdź stronę Skrzynka
Zmienić konta klientaDane konta są tylko do odczytu. Zmiany wprowadzasz w helpdesku i w swoim panelu

Jeśli coś nie działa

Co widziszCo zrobić
Zalogowany klient pisze na czacie jako gośćOtwórz źródło strony: data-konrado-user-token musi zawierać token. Sprawdź, czy serwer ma aktualny klucz, czy sub jest ciągiem znaków, czy iat i exp są w pełnych sekundach i czy jest jti. Zegar serwera nie może się spóźniać o więcej niż 5 minut, bo wtedy każdy token przychodzi wygasły. Token dłuższy niż 4096 znaków jest odrzucany.
Klienci piszą jako goście tylko na niektórych stronachTe strony pochodzą z pamięci podręcznej (cache), więc zawierają stary token, który został już użyty albo wygasł. Każdy token działa raz: nie zapisuj stron dla zalogowanych w pamięci podręcznej.
Rozmowa zalogowanego klienta zaczyna się od nowa, gdy otwiera on inną stronęTa strona podpisuje go innym sub albo inną wartością platform, na przykład z platform na stronach WHMCS i bez niego na pozostałych. Czat uznaje to za innego klienta. Podpisuj ten sam sub i tę samą wartość platform na każdej stronie.
Agent zna imię i nazwisko, ale nie kontosub nie jest ID klienta w Twoim helpdesku albo nie jest ID klienta WHMCS, gdy SupportPal jest połączony z WHMCS. Jeśli wysyłasz platform, musi ono wskazywać system, z którym czat jest połączony. WordPress wysyła wp: i ID użytkownika, chyba że ustawisz przypisanie.
Przy SupportPal połączonym z WHMCS do agenta trafia tylko część kontaDrugi system znajduje klienta po adresie e-mail: dokładnie jeden klient w tym systemie musi mieć e-mail klienta, którego podpisujesz. Bez platform podpisujesz klienta WHMCS, więc tego dopasowania wymagają zgłoszenia i profil. Z platform ustawionym na supportpal wymagają go usługi i faktury.
Na stronie Skrzynka nie ma oznaczenia zalogowanyDo agenta nie jest podłączony żaden helpdesk albo platform wskazuje system, z którym czat nie jest połączony. Agent nadal ma imię i nazwisko oraz e-mail z tokenu, a następna osoba w przeglądarce nadal nie może otworzyć tej rozmowy.
Rozpoznawanie przestało działać po drugiej wymianieTwój serwer podpisuje kluczem sprzed dwóch wymian. Skopiuj aktualny klucz z sekcji Weryfikacja tożsamości i wdróż go.

Ostatnia aktualizacja:

Na tej stronie