Řešení problémů

Tuto stránku použijte, když je widget nainstalován, ale nechová se podle očekávání.

Widget se nezobrazuje

Nejprve zkontrolujte konzolu prohlížeče. ChattyBox v ní hlásí chybějící povinné atributy.

Běžné příčiny:

• Skript chybí v nasazeném HTML i v aktuálním DOM.
• Skript byl přidán do nesprávné šablony, rozvržení, kontejneru správce značek nebo oblasti kódu CMS.
• Skript blokuje pravidlo souhlasu nebo spouštěč správce značek, který se nespustil.
• Komponenta aplikace, která připojuje loader, se na této trase nespustí.
• Zásady zabezpečení obsahu blokují https://chattybox.ai/widget.js.
• CSS nebo jiný widget překrývá spouštěcí tlačítko.
• Nasazená konfigurace obsahuje widget.enabled: false.

Nejmenší oprava:

1. Otevřete nasazenou veřejnou stránku v anonymním okně.
2. Vyhledejte chattybox.ai/widget.js ve zdrojovém kódu stránky i v panelu Elements prohlížeče; loader vložený SDK nebo JavaScriptem může být viditelný pouze v aktuálním DOM.
3. Ověřte, že se skript zobrazuje právě jednou a obsahuje data-api-key a data-api-url.
4. Pokud skript chybí, přesuňte jej do globální patičky, rozvržení aplikace, kořenového adresáře Docusaurus nebo na spouštěč GTM All Pages.

U projektů spravovaných konfigurací widget.enabled: false zabrání inicializaci hostovaného widgetu a způsobí, že veřejné požadavky POST /chat vracejí 403 Widget is disabled; platí to i pro požadavky headless SDK. Toto nastavení změňte v rámci procesu nasazení konfigurace, nikoli rotací veřejného klíče. Odstranění skriptu loaderu po inicializaci neodstraní již vykreslený widget.

Chybí data-api-url

Widget se předčasně ukončí, pokud chybí data-api-url.

Použijte celý úryvek z řídicího panelu nebo přidejte požadovaný atribut:

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

Použijte adresu API z řídicího panelu a nehádejte ji. V produkci se očekává stabilní adresa https://...convex.site/chat.

Obecná chyba 401 Invalid API key

Z bezpečnostních důvodů vracejí koncové body API widgetu stejnou obecnou chybu 401 Invalid API key pro neznámý, prošlý nebo kvůli originu odmítnutý veřejný klíč. Ze samotné odpovědi příčinu nepoznáte.

Běžné příčiny:

• Veřejný klíč widgetu byl zkopírován nesprávně.
• Klíč byl odstraněn, vypršel nebo pochází z jiného nasazení backendu než adresa API.
• Projekt nebo vlastník klíče se odstraňuje.
• Pro klíč je zapnuté volitelné omezení originů a aktuální origin webu není na seznamu.

Opravy:

1. Otevřete projekt v řídicím panelu ChattyBox.
2. Otevřete Instalace → Instalace na web, zadejte URL webu a zkopírujte způsobilý úryvek, pokud je k dispozici.
3. Na stejné stránce v části Klíče a domény použijte Upravit originy pro klíč v nainstalovaném úryvku. Pokud je zapnuté Omezit tento klíč na konkrétní originy, přidejte přesný origin stránky nebo volitelné omezení vypněte. Musí souhlasit schéma, název hostitele i port: https://example.com, https://preview.example.com a http://localhost:3000 jsou různé originy. Cesty není třeba zadávat zvlášť.
4. Web znovu nasaďte nebo publikujte a otestujte v anonymním okně.

Platný klíč pro jiného chatbota na stejném backendu obvykle vybere tohoto chatbota, místo aby způsobil 401; pokud jsou odpovědi nesouvisející, zkontrolujte projekt. Názvy klíčů jako „production“ a „staging“ prostředí nevynucují. HTTP API používá hlavičku Origin, pokud je přítomna; pouze pokud chybí, použije origin z hlavičky Referer. Omezený klíč odmítne požadavek, pokud tento vybraný origin chybí, je neplatný nebo není povolený. Povolený Referer nepřebije nepovolený Origin. Omezení originů nenahrazuje ověřování návštěvníků.

Limity zpráv a požadavků

Na stránce Account & Billing na adrese /settings/account zkontrolujte využití zpráv, tarif a případné rozpočty PAYG pro Pro/Business. Test Chat i veřejný chat čerpají ze společného limitu zpráv vlastníka. Mazání konverzací ani vytvoření dalšího klíče tento limit neresetuje.

Chyby měsíčního limitu a krátkodobé limity požadavků jsou různé věci. U odpovědí HTTP 429 dodržujte hlavičku Retry-After, pokud je uvedena, místo opakovaného odesílání požadavků. Při chybě měsíčního limitu zpráv počkejte na jeho obnovení nebo upravte tarif či způsobilý rozpočet PAYG. Konverzace → Historie obsahuje historii konverzací, nikoli konzoli chyb jednotlivých požadavků; chyby HTTP kontrolujte v panelu Network prohlížeče.

Nesprávný jazyk

Nejprve zkontrolujte nastavení jazyka widgetu v Customize → Appearance. Hostovaný widget z aktuálního zdrojového kódu vybírá jazyk rozhraní v tomto pořadí:

1. data-locale ve skriptu widgetu — pouze pokud je povolené Allow script override.
2. V režimu Fixed nakonfigurovaný výchozí jazyk.
3. V režimu Auto-detect hodnota <html lang> stránky, poté podporované jazykové kandidáty prohlížeče a nakonec nakonfigurovaný výchozí jazyk.

Nepodporované jazykové kandidáty se přeskočí. Pokud není podporován žádný kandidát, konečným záložním jazykem je angličtina; výchozí jazyk je zpočátku nastaven na angličtinu.

Opravy:

• Pro automatický výběr jazyka zvolte Auto-detect a odstraňte nesprávné data-locale nebo zakažte přepisování skriptem.
• Na lokalizovaných stránkách nastavte <html lang="de">, <html lang="fr"> nebo odpovídající podporovaný kód jazyka.
• Chcete-li vynutit nakonfigurovaný jazyk, zvolte Fixed a vypněte Allow script override. Pokud je přepisování povolené, data-locale má přednost i v režimu Fixed.
• Zkontrolujte, zda se nastavení uložilo, znovu inicializujte nainstalovaný widget, aby načetl konfiguraci z řídicího panelu, a znovu jej otestujte. Hostovaný widget.js v16 z aktuálního zdrojového kódu může aktualizovat štítky produktu, když změna <html lang> nebo data-locale loaderu změní rozpoznaný jazyk. Než se spolehnete na aktualizaci za běhu, ověřte nasazenou verzi loaderu; toto chování hostovaného loaderu je nezávislé na publikovaném balíčku npm SDK 0.1.4. Hodnota locale předaná do mountWidget() se změní na data-locale a podléhá stejným pravidlům projektu.
• Pokud widget není dostupný, zkontrolujte požadavek /widget-config a veřejný klíč. Při neúspěšném načtení konfigurace hostovaný widget.js v16 z aktuálního zdrojového kódu ponechá widget nedostupný, místo aby jej spustil s výchozím nastavením. Než se na toto chování spolehnete, ověřte nasazenou verzi loaderu.
• Pokud odpovědi citují nebo načítají obsah v nesprávném jazyce, zaindexujte každou požadovanou jazykovou verzi. Generátor odpovědí rozpoznává jazyk podle otázky, nezávisle na jazyku rozhraní widgetu; jazyk Fixed nevynucuje jazyk odpovědi ani nepřekládá zdrojový obsah. Pokud není nastavena vlastní hodnota assistant.fallbackMessage, vestavěná vynucená odpověď při chybějícím obsahu použije detekovaný jazyk otázky, pokud je to vhodné; při nejisté detekci použije jazyk rozhraní widgetu a angličtina je až poslední záložní možností.

Chybějící citace nebo slabé odpovědi

ChattyBox používá k vytváření odpovědí vyhledaný zdrojový obsah. Chybějící citace nebo slabé odpovědi mohou být důsledkem chybějícího či nevhodného zdrojového obsahu, problémů s vyhledáváním nebo selhání generování; samy o sobě příčinu neurčují.

Uzemněnému RAG chatbotovi pomáhá jasný vyhledaný zdrojový obsah, ale samotná citace odpověď neověřuje. Každé důležité tvrzení porovnejte s citovanou stránkou.

Opravy:

• Položte stejnou otázku v testovacím chatu řídicího panelu a porovnejte citované stránky.
• Ověřte, že je zdrojová stránka veřejná a zahrnutá do crawlování.
• Na zdrojovou stránku přidejte jasné nadpisy, příklady, FAQ a přímé odpovědi.
• Nespoléhejte se pouze na snímky obrazovky, videa, vyloučené skryté značky, obsah dostupný jen přes JavaScript nebo iframe.
• Aktualizovanou stránku znovu seškrábejte, až to dovolí cooldown, počkejte na dokončení embeddingu a potom test zopakujte.
• Hledejte upozornění Partially indexed; text nad limitem 512 KiB na stránku se neuchovává. Dlouhé zdrojové stránky rozdělte, místo opakovaného vytváření indexu stejného zkráceného textu.
• Pokud možno formulujte každou otázku jasně a samostatně. Generátor odpovědí může dostat až 12 posledních uložených zpráv, každou o délce nejvýše 2 000 znaků; nedostává celý přepis konverzace.

Persona přidává pokyny specifické pro web k vestavěným pravidlům uzemnění; nemůže dodat chybějící zaindexovaný obsah ani nahradit záložní odpověď při chybějícím kontextu nebo nedostatku obsahu, když je tato odpověď spuštěna. Detektor mezer v obsahu je heuristický a nemusí zachytit každou nepodloženou odpověď. Tato záložní odpověď má samostatné nastavení assistant.fallbackMessage v configuration as code.

Stránky se nescrapují nebo obsah zastaral

Běžné příčiny:

• Stránka chybí v odeslané mapě webu.
• Režim ručních URL stránku nezahrnoval.
• Stránka blokuje běžné HTTP načítání, vyžaduje ověření, vrací stránku CAPTCHA/chyby nebo přesměrovává na blokovaný cíl.
• Obsah stránky se změnil po posledním scrapování.
• Obsah se vykresluje pouze pomocí JavaScriptu nebo leží mimo vybraný sémantický kořen obsahu.
• Vybrané URL překročily limit stránek, vyčerpal se měsíční rozpočet obnovování nebo je odfiltrovalo pravidlo include/exclude.

Opravy:

1. Ověřte, že se stránka veřejně otevře v soukromém okně prohlížeče.
2. Pro široké pokrytí použijte režim mapy webu, pro vybranou sadu ruční adresy URL.
3. Místo měřicí URL, URL přesměrování nebo přihlašovací URL odešlete kanonickou adresu.
4. Po zveřejnění změn stránku znovu seškrábejte až po uplynutí cooldownu obnovování: u tarifu Free nejméně sedm dní od vytvoření poslední úlohy, u placených tarifů 24 hodin — i když poslední úloha selhala.
5. V části Znalosti → Stránky rozbalte Historie importu, pokud existují úlohy, a vyberte úlohu v panelu Úlohy scrapingu. Porovnejte její uložené/vybrané počty a seznam Stránky se zamýšlenými URL. Stav Completed může zahrnovat přeskočené nebo neúspěšné URL. Completed with warnings označuje konkrétně částečně zachovaný text stránky, nikoli všechna selhání crawlování. Rozhraní neposkytuje úplný seznam chyb pro jednotlivé URL.

ChattyBox nevynucuje pokyny pro crawlování z robots.txt; může tento soubor přečíst kvůli zjištění deklarací map webu. Nepovažujte robots.txt za řízení přístupu. ChattyBox bezpečně následuje HTTP přesměrování, takže samotné přesměrování není chyba. Neodstraňujte ochranu přístupu ani nezveřejňujte soukromý obsah, aby jej bylo možné crawlovat.

Pokud byla URL odstraněna z webu nebo výběru zdrojů, uložená stránka se může dál používat. Odstraňte ji také v části Znalosti → Stránky a vylučte ji z budoucího vyhledávání. Rebuild Index používá uložený text, nikoli nové načtení ze sítě; má vlastní cooldown podle tarifu a čerpá z měsíčního rozpočtu obnovování.

Nastavení se neukládá

Změny údajů o chatbotu a nastavení zdrojů se ukládají automaticky. Než budete pokračovat, zkontrolujte stav ukládání, vyřešte chyby ověření nebo zopakujte neúspěšné uložení. Řídicí panel vyžaduje uloženou hodnotu Website URL, i když zadáváte Manual URLs. Vyhledání stránek ani automatické ukládání samo o sobě nespustí import; zkontrolujte vybrané stránky a import spusťte výslovně.

Pokud má projekt stav Config locked, konfiguraci je nutné nasazovat prostřednictvím postupu CLI. Zámek je nevratný; ukládání Persona, konfigurace scrapování, akce Scrape Now, mazání obsahu a opětovné sestavení indexu jsou odmítnuty, i když jsou ovládací prvky stále viditelné. V konfiguraci hostovaného widgetu zůstává v řídicím panelu upravitelná pouze předvolba brandingu, a to podle tarifu. Veřejné klíče widgetu a deployment tokeny jsou samostatné přihlašovací údaje.

Pokud projekt chybí nebo byl přístup odepřen, ověřte, že jste přihlášeni jako jeho vlastník. Klíč widgetu, deployment token ani členství v organizaci neudělují oprávnění vlastníka řídicího panelu. V části Konverzace jsou Analytika a Nezodpovězené otázky součástí tarifů Pro a Business; u nedostupných zobrazení se zobrazí výzva k upgradu. Historie je dostupná ve všech tarifech.

Stále máte problém

Před kontaktováním podpory si připravte tyto údaje:

• URL veřejné stránky, na které se má widget zobrazit.
• Snímek obrazovky nebo kopii chyby z konzoly prohlížeče.
• Zda stránka používá běžné HTML, Next.js, Docusaurus, WordPress, CMS nebo Google Tag Manager.
• Zda úryvek obsahuje data-api-key a data-api-url.
• Jednu testovací otázku, která by měla fungovat, a zdrojovou stránku, která na ni odpovídá.