Przejdź do głównej treści

Rozwiązywanie problemów

Użyj tej strony, jeśli widget jest zainstalowany, ale nie zachowuje się zgodnie z oczekiwaniami.

Widget nie pojawia się​

Najpierw sprawdź konsolę przeglądarki. ChattyBox zgłasza tam brak wymaganych atrybutów.

Najczęstsze przyczyny:

  • Skryptu nie ma ani we wdrożonym HTML, ani w bieżącym DOM.
  • Skrypt dodano do niewłaściwego szablonu, układu, kontenera menedżera tagów lub obszaru kodu CMS.
  • Skrypt jest objęty regułą zgody lub wyzwalaczem menedżera tagów, który się nie uruchomił.
  • Komponent aplikacji montujący loader nie uruchamia się na tej trasie.
  • Polityka bezpieczeństwa treści blokuje https://chattybox.ai/widget.js.
  • CSS lub inny widget nakłada się na przycisk uruchamiający.
  • Wdrożona konfiguracja zawiera widget.enabled: false.

Najmniejsza poprawka:

  1. Otwórz wdrożoną stronę publiczną w oknie incognito.
  2. Wyszukaj chattybox.ai/widget.js w źródle strony i w panelu Elements przeglądarki; loader wstrzyknięty przez SDK lub JavaScript może być widoczny tylko w bieżącym DOM.
  3. Upewnij się, że skrypt pojawia się raz i zawiera data-api-key oraz data-api-url.
  4. Jeśli skryptu brakuje, przenieś go do globalnej stopki, układu aplikacji, katalogu głównego Docusaurus albo wyzwalacza GTM All Pages.

W projektach zarządzanych przez konfigurację widget.enabled: false uniemożliwia inicjalizację hostowanego widgetu i powoduje, że publiczne żądania POST /chat zwracają 403 Widget is disabled — dotyczy to także żądań headless SDK. Zmień to ustawienie w ramach procesu wdrażania konfiguracji, a nie przez rotację klucza publicznego. Usunięcie skryptu loadera po inicjalizacji nie usuwa już wyrenderowanego widgetu.

Brakuje data-api-url​

Widget kończy działanie wcześniej, gdy brakuje data-api-url.

Użyj pełnego fragmentu z panelu albo dodaj wymagany atrybut:

<script
  src="https://chattybox.ai/widget.js"
  data-api-key="YOUR_API_KEY"
  data-api-url="YOUR_WIDGET_API_URL"
  async
></script>

Użyj adresu URL API z panelu zamiast zgadywać. W środowisku produkcyjnym powinien to być stabilny adres https://...convex.site/chat.

Ogólny błąd 401 Invalid API key​

Ze względów bezpieczeństwa endpointy API widgetu zwracają ten sam ogólny błąd 401 Invalid API key dla nieznanego, wygasłego lub odrzuconego z powodu originu klucza publicznego. Nie próbuj ustalać przyczyny na podstawie samej odpowiedzi.

Najczęstsze przyczyny:

  • Klucz publicznego widgetu został skopiowany niepoprawnie.
  • Klucz został usunięty, wygasł albo pochodzi z innego wdrożenia backendu niż adres URL API.
  • Projekt lub właściciel klucza jest usuwany.
  • Dla klucza włączono opcjonalne ograniczenie originów, a origin bieżącej witryny nie jest na liście.

Poprawki:

  1. Otwórz projekt w panelu ChattyBox.
  2. Otwórz Instalacja → Instalacja na stronie, wpisz adres URL witryny i skopiuj odpowiedni fragment kodu, jeśli jest dostępny.
  3. W sekcji Klucze i domeny na tej samej stronie wybierz Edytuj originy dla klucza z zainstalowanego fragmentu kodu. Jeśli włączono Ogranicz ten klucz do określonych originów, dodaj dokładny origin strony albo wyłącz to opcjonalne ograniczenie. Protokół, nazwa hosta i port muszą się zgadzać: https://example.com, https://preview.example.com i http://localhost:3000 to różne originy. Ścieżek nie trzeba dodawać osobno.
  4. Wdróż lub opublikuj witrynę ponownie i przetestuj ją w oknie incognito.

Prawidłowy klucz innego chatbota na tym samym backendzie zwykle wybiera tamtego chatbota, zamiast powodować 401; jeśli odpowiedzi są niepowiązane z pytaniem, sprawdź projekt. Nazwy kluczy, takie jak „production” i „staging”, nie wyznaczają środowisk. HTTP API używa nagłówka Origin, jeśli jest obecny; tylko gdy go brakuje, korzysta z originu nagłówka Referer. Klucz z ograniczeniem odrzuca żądanie, jeśli wybrany origin jest nieobecny, nieprawidłowy lub niedozwolony. Dozwolony Referer nie zastępuje niedozwolonego Origin. Ograniczenia originów nie zastępują uwierzytelniania odwiedzających.

Limity wiadomości i żądań​

Sprawdź Rozliczenia i wykorzystanie pod adresem /settings/account, aby zobaczyć wykorzystanie wiadomości, plan oraz opcjonalne budżety PAYG dla Pro/Business. Testy w panelu i czat publiczny korzystają ze wspólnego limitu wiadomości właściciela. Usuwanie rozmów ani tworzenie kolejnego klucza nie resetuje tego limitu.

Błędy miesięcznego limitu i krótkoterminowe limity żądań to różne rzeczy. W przypadku odpowiedzi HTTP 429 przestrzegaj nagłówka Retry-After, jeśli został zwrócony, zamiast ponawiać żądania w kółko. Przy błędzie miesięcznego limitu wiadomości poczekaj na reset limitu albo zmień plan lub kwalifikujący się budżet PAYG. Widok Rozmowy → Historia zawiera historię rozmów, a nie konsolę błędów poszczególnych żądań; błędy HTTP sprawdzaj w panelu Network przeglądarki.

Nieprawidłowy język​

Najpierw sprawdź ustawienia języka widgetu w Personalizacja → Wygląd. Hostowany widget z bieżącego kodu źródłowego wybiera język interfejsu w tej kolejności:

  1. data-locale w skrypcie widgetu — tylko gdy włączono Zezwalaj na nadpisanie przez skrypt.
  2. W trybie Stały — skonfigurowany język domyślny.
  3. W trybie Wykryj automatycznie — wartość <html lang> strony, następnie języki przeglądarki, a na końcu skonfigurowany język domyślny.

Nieobsługiwane wartości kandydatów są pomijane. Jeśli żaden kandydat nie jest obsługiwany, ostatecznym językiem zapasowym jest angielski; początkowym językiem domyślnym jest angielski.

Poprawki:

  • Przy automatycznym wyborze języka wybierz Wykryj automatycznie i usuń nieprawidłowe data-locale albo wyłącz nadpisywanie przez skrypt.
  • Ustaw <html lang="de">, <html lang="fr"> lub pasujący kod języka na zlokalizowanych stronach.
  • Aby wymusić skonfigurowany język, wybierz Stały i wyłącz Zezwalaj na nadpisanie przez skrypt. Gdy nadpisywanie jest włączone, data-locale ma pierwszeństwo także w trybie Stały.
  • Sprawdź, czy ustawienia zostały zapisane, uruchom ponownie zainstalowany widget, aby pobrał konfigurację z panelu, i przetestuj go ponownie. Hostowany widget.js v16 z bieżącego kodu źródłowego może aktualizować etykiety należące do produktu, gdy zmiana <html lang> lub data-locale loadera zmieni wykryty język. Przed poleganiem na aktualizacji na żywo sprawdź wersję wdrożonego loadera; to zachowanie hostowanego loadera jest niezależne od opublikowanego pakietu npm SDK 0.1.4. Opcja locale przekazana do mountWidget() staje się data-locale i podlega tym samym zasadom projektu.
  • Jeśli widget jest niedostępny, sprawdź żądanie /widget-config i klucz publiczny. Jeśli pobranie konfiguracji się nie powiedzie, hostowany widget.js v16 z bieżącego kodu źródłowego pozostawia widget niedostępny zamiast uruchamiać go z ustawieniami domyślnymi. Przed poleganiem na tym zachowaniu sprawdź wersję wdrożonego loadera.
  • Zindeksuj każdą wymaganą wersję językową, jeśli odpowiedzi cytują lub pobierają treści w niewłaściwym języku. Generator odpowiedzi wykrywa język na podstawie pytania, niezależnie od języka interfejsu widgetu; język Fixed nie wymusza języka odpowiedzi ani nie tłumaczy treści źródłowych. Jeśli nie skonfigurowano własnej wartości assistant.fallbackMessage, wbudowana wymuszona odpowiedź przy braku treści używa wykrytego języka pytania, gdy jest to odpowiednie; przy niepewnym wykryciu używa języka interfejsu widgetu, a angielski jest ostatecznym językiem zapasowym.

Brak cytowań lub słabe odpowiedzi​

ChattyBox używa pobranych treści źródłowych do generowania odpowiedzi. Brak cytowań lub słabe odpowiedzi mogą wynikać z brakujących lub nieodpowiednich treści źródłowych, problemów z ich pobieraniem albo błędów generowania; same w sobie nie wskazują przyczyny.

Ugruntowany chatbot RAG korzysta z jasnych, pobranych treści źródłowych, ale samo cytowanie nie potwierdza poprawności odpowiedzi. Porównaj każde ważne stwierdzenie z cytowaną stroną.

Poprawki:

  • Zadaj to samo pytanie w czacie testowym panelu i porównaj cytowane strony.
  • Upewnij się, że strona źródłowa jest publiczna i uwzględniona w crawlowaniu.
  • Dodaj na stronie źródłowej jasne nagłówki, przykłady, FAQ i bezpośrednie odpowiedzi.
  • Nie polegaj wyłącznie na zrzutach ekranu, filmach, wykluczonych ukrytych znacznikach, treściach dostępnych tylko przez JavaScript ani iframe.
  • Zeskrob ponownie zaktualizowaną stronę, gdy pozwala na to cooldown; poczekaj na zakończenie osadzania, a potem przetestuj ponownie.
  • Sprawdź ostrzeżenia Partially indexed; tekst przekraczający limit 512 KiB na stronę nie jest zachowywany. Dziel długie strony zamiast wielokrotnie przebudowywać ten sam ucięty tekst.
  • W miarę możliwości formułuj każde pytanie jasno i samodzielnie. Generator odpowiedzi może otrzymać do 12 ostatnich zapisanych wiadomości, każdą o długości najwyżej 2 000 znaków; nie otrzymuje pełnego transkryptu rozmowy.

Persona dodaje instrukcje specyficzne dla witryny do wbudowanych reguł ugruntowania; nie zastąpi brakujących zindeksowanych treści ani odpowiedzi zapasowej przy braku kontekstu lub lukach w treści, gdy zostanie ona uruchomiona. Detektor luk w treści działa heurystycznie i może nie wykryć każdej odpowiedzi bez oparcia w źródłach. Ta odpowiedź zapasowa ma osobne ustawienie assistant.fallbackMessage w configuration as code.

Strony nie są crawlowane lub zawierają nieaktualne treści​

Najczęstsze przyczyny:

  • Strony brakuje w przesłanej mapie witryny.
  • Tryb ręcznych adresów URL nie obejmuje tej strony.
  • Strona blokuje zwykłe pobieranie HTTP, wymaga uwierzytelnienia, zwraca stronę CAPTCHA/błędu albo przekierowuje do zablokowanego celu.
  • Treść strony zmieniła się po ostatnim crawlowaniu.
  • Treść jest renderowana wyłącznie przez JavaScript albo znajduje się poza wybranym semantycznym korzeniem treści.
  • Wybrane adresy URL przekroczyły limit stron, wyczerpał się miesięczny budżet odświeżania albo odfiltrowała je reguła include/exclude.

Poprawki:

  1. Potwierdź, że strona otwiera się publicznie w prywatnym oknie przeglądarki.
  2. Użyj trybu mapy witryny, aby objąć wiele stron, albo ręcznych adresów URL dla wybranego zestawu.
  3. Prześlij kanoniczny adres URL zamiast adresu śledzącego, URL przekierowania lub adresu dostępnego po zalogowaniu.
  4. Zeskrob ponownie po opublikowaniu zmian i upływie cooldownu odświeżania: co najmniej siedem dni od utworzenia najnowszego zadania w planie Free lub 24 godziny w planach płatnych — także jeśli zadanie się nie powiodło.
  5. W Baza wiedzy → Strony rozwiń Historia importu, gdy istnieją zadania, i wybierz zadanie w sekcji Zadania scrapingu. Porównaj jego liczby zapisanych i wybranych stron oraz listę Strony z oczekiwanymi adresami URL. Status Completed może obejmować pominięte lub nieudane adresy. Completed with warnings oznacza konkretnie częściowo zachowany tekst strony, a nie wszystkie błędy crawlowania. Interfejs nie pokazuje kompletnej listy błędów dla poszczególnych adresów.

ChattyBox nie egzekwuje dyrektyw crawlowania z robots.txt; może odczytać ten plik, aby znaleźć deklaracje map witryny. Nie traktuj robots.txt jako kontroli dostępu. ChattyBox bezpiecznie obsługuje przekierowania HTTP, więc samo przekierowanie nie oznacza błędu. Nie usuwaj zabezpieczeń dostępu ani nie umieszczaj prywatnych treści pod publicznym adresem URL, aby umożliwić ich crawlowanie.

Jeśli adres URL usunięto z witryny lub wyboru źródeł, zapisana strona może nadal być używana. Usuń ją również w Baza wiedzy → Strony i wyklucz z przyszłego wykrywania. Przebuduj indeks korzysta z zapisanego tekstu, a nie z nowego pobrania z sieci; ma własny cooldown zależny od planu i wykorzystuje miesięczny budżet odświeżania.

Ustawienia się nie zapisują​

Zmiany szczegółów chatbota i ustawień źródeł są zapisywane automatycznie. Przed kontynuowaniem sprawdź status zapisu, usuń błędy walidacji lub ponów nieudany zapis. Panel wymaga zapisanego Adresu URL strony nawet w trybie Ręczne adresy URL. Wykrywanie stron i automatyczny zapis same nie rozpoczynają importu — sprawdź wybrane strony i jawnie rozpocznij import.

Jeśli projekt ma blokadę konfiguracji, konfigurację trzeba wdrażać przez proces CLI. Blokada jest nieodwracalna; zapisywanie persony, konfiguracji skanowania, użycie Zbieraj teraz, usuwanie treści i przebudowa indeksu są odrzucane, nawet jeśli odpowiednie elementy sterujące są widoczne. W konfiguracji hostowanego widgetu w panelu można nadal edytować wyłącznie preferencje brandingu, zależnie od planu. Publiczne klucze widgetu i tokeny wdrożeniowe to osobne dane uwierzytelniające.

Jeśli brakuje projektu lub odmówiono dostępu, upewnij się, że zalogowano się jako jego właściciel. Klucz widgetu, token wdrożeniowy ani członkostwo w organizacji nie przyznają uprawnień właściciela panelu. W sekcji Rozmowy widoki Analityka i Pytania bez odpowiedzi są dostępne w planach Pro lub Business; niedostępne widoki proponują zmianę planu. Historia jest dostępna we wszystkich planach.

Nadal utknąłem​

Zbierz te dane przed skontaktowaniem się z pomocą techniczną:

  • Adres URL strony publicznej, na której powinien pojawić się widget.
  • Zrzut ekranu lub kopia dowolnego błędu konsoli przeglądarki.
  • Czy strona używa zwykłego HTML, Next.js, Docusaurus, WordPress, CMS lub Google Tag Manager.
  • Czy fragment zawiera data-api-key i data-api-url.
  • Jedno pytanie testowe, które powinno działać, i strona źródłowa, która na nie odpowiada.