Veřejné JavaScript API¶

Vše, co může vaše stránka použít k ovládání vloženého chatovacího widgetu z vlastního JavaScriptu.

Widget běží ve vlastním Shadow DOM přímo ve vaší stránce — nejde o iframe, takže všechna API volání jsou normální JavaScript, nic neběží izolovaně. Vše se odehrává přes dva globální objekty:

Globální proměnná	Kdo ji nastavuje	K čemu slouží
`window.daktelaAiChatConfig`	vaše stránka	odkud se má widget načíst
`window.daktelaAiChat`	widget	API popsané níže

Instalace¶

Embed kód najdete v záložce CODE publikačního panelu vedle nastavení widgetu. Vložte ho na stránku jako jeden blok — nese konfiguraci, nainstaluje frontu příkazů a načte samotný widget.

<script>
  window.daktelaAiChatConfig = {
      url: "https://my-instance.bot.coworkers.ai",
      daktelaAiChatId: "abc123",
  };

  (function(){var e=window.daktelaAiChatConfig;if(!window.daktelaAiChat||!window.daktelaAiChat.__isProxy){var t=[];window.daktelaAiChat=new Proxy({queue:t,__isProxy:!0},{get:function(e,n){return n in e?e[n]:function(){var e={m:n,a:[].slice.call(arguments),t:Date.now()};return t.push(e),new Promise(function(t,n){e.resolve=t,e.reject=n})}}})}var n=document.createElement(`script`);n.defer=!0,n.crossOrigin=`anonymous`,n.src=e.url.replace(/\/+$/,``)+`/chat-window-public-api/loader/dai-loader.js`,document.head.appendChild(n)})();
</script>

Jediná část snippetu určená k úpravám je daktelaAiChatConfig.

Jak funguje načítání¶

Widget se stahuje až ve chvíli potřeby (lazy) — třeba při open() nebo kliknutí na launcher. Cokoli zavoláte předtím, se jen zapíše do fronty a jakmile se widget načte, provede se to celé přesně v tom pořadí, v jakém jste to volali — nic se neztratí.

Každé volání ve frontě vrací promise, takže await funguje i před načtením widgetu:

const result = await window.daktelaAiChat.authorize(jwt);

Výjimkou je getRegisteredTools(): před načtením widgetu nemá co hlásit, takže její výsledek má vypovídací hodnotu až za běhu.

Ovládání okna¶

`open()`¶

Otevře chatovací okno. Při prvním zavolání spustí lazy download. Klidně ho volejte víckrát za sebou, nic se tím nepokazí.

`close()`¶

Zavře okno a defaultně tím i ukončí konverzaci: configuration.identity.closeResetsSession je defaultně true, takže se session resetuje a příští otevření začne novou diskuzi. Když tuhle volbu nastavíte na false, close() okno jen schová.

`restart(options?)` / `restartAndOpen(options?)`¶

Zahodí aktuální konverzaci a začne novou. restartAndOpen k tomu ještě otevře okno.

window.daktelaAiChat.restart({ retainContextKeys: ['$orderId'] });

Volba	Typ	Efekt
`retainContextKeys`	`string[]`	Klíče kontextu, které se zkopírují do nové konverzace. Všechno ostatní se zahodí. Neznámé klíče se ignorují.

Bez zadaných voleb se zahodí celý kontext.

`restartAndClose()`¶

Zavře okno. Navzdory názvu konverzaci neresetuje — jestli session skončí, rozhoduje closeResetsSession, úplně stejně jako u close().

`destroy()`¶

Widget odpojí, smaže ho z DOM, vyčistí registrované nástroje i analytiku a odstraní window.daktelaAiChat. Použijte, když vaše stránka chat ruší — třeba při přechodu na jinou route v SPA. Cokoli zavoláte potom, už nemá žádný efekt.

Identita¶

Identita je způsob, jak widgetu sdělíte, kdo návštěvník je, aby se historie konverzací vázala na osobu, a ne na prohlížeč. Widget vám to nevezme na slovo — předkládá token podepsaný vaším identity providerem a platforma si ho ověří.

Nastavení (podpisový klíč, claimy, délka session) popisuje stránka Autentizace návštěvníků. Tato sekce je přehled metod.

`authorize(jwt, refreshJwt?)`¶

const result = await window.daktelaAiChat.authorize(
  jwt,
  async () => fetchFreshJwt(),   // zavolá se, když session vyprší
);

if (!result.authorized) {
  console.warn('Chat authorization failed:', result.reason);
}

Ověří jwt a přepne chat na výslednou session.

Volání se vždy dokončí úspěšně — token, který ověřením neprojde, se vrátí jako { authorized: false, reason }, nikoli výjimkou, takže volání bez await nemůže skončit neošetřeným rejectem. reason nabývá hodnot invalid_token, not_configured, network_error nebo superseded.

Druhý parametr je funkce, kterou chat zavolá pro nový token po vypršení session. Musí vrátit token, který je ještě platný — a může to být i ten samý jako předtím: vyprší session chatu, ne váš token, takže uložený token, jehož platnost ještě neskončila, je v pořádku. Token s prošlou platností, prázdná hodnota, výjimka nebo funkce, která se nikdy nedokončí, návštěvníka odhlásí místo opakování pokusu.

Tip

Doporučený okamžik je načtení stránky, jakmile je token k dispozici — nikoli až otevření chatu. Session patří jedné kartě prohlížeče, takže vracející se návštěvník žádnou nemá, dokud toto volání neproběhne. Pozdější volání funguje a nic se neztratí, ale stojí to jedno kolo dotazů navíc a viditelné obnovení spojení.

Samotné authorize() nestáhne balík chatu. Dokud načtení nevyvolá něco jiného — open() nebo kliknutí návštěvníka na launcher — zůstává volání jen ve frontě.

`startDiscussion(userToken?)`¶

Přepne návštěvníka na jinou konverzaci, nebo bez argumentu založí novou. Server stále kontroluje, že konverzace patří tomuto návštěvníkovi, a jinak ji odmítne.

Kdy voláte	Co se stane
Před otevřením okna chatu	Handle se převezme a konverzace vznikne pod ním. Nic se nezahazuje, protože nic ještě nezačalo.
V průběhu chatování	Spojení se přesune na druhou konverzaci a spolu s ním se smaže i přepis na obrazovce — ponechat staré zprávy by znamenalo ukazovat konverzaci, ke které už spojení nepatří.
S handlem, který se už používá	Nic.

Handle, který návštěvníkovi nepatří, server odmítne a widget se z toho zotaví sám: odmítnutý handle zahodí a začne vlastní konverzaci. To je dobré vědět, pokud si vaše stránka drží handle přes odhlášení — konverzace z doby před odhlášením už návštěvníkovi nepatří a vrácením handlu ji nelze znovu otevřít.

Handle ukazující na ukončenou konverzaci je jiný případ: otevře se jen pro čtení, s přepisem na obrazovce a zamčeným vstupním polem. Je to konverzace, kterou návštěvník měl, takže se mu ukáže, místo aby mu byla vzata; tlačítko pro začátek nové nese závěrečná zpráva bota.

Konverzaci, kterou návštěvník opouští, neukončí — ta zůstane na serveru otevřená, takže se k ní lze později vrátit. Pokud ji ukončit chcete, zavolejte nejdřív finishDiscussion():

await window.daktelaAiChat.finishDiscussion();
window.daktelaAiChat.startDiscussion(nextUserToken);

`finishDiscussion()`¶

Ukončí aktuální diskuzi na serveru a okno nechá přesně tak, jak je — přepis zůstane na obrazovce a vykreslí se jen pro čtení, jako u každého ukončeného chatu. Nic se nezavírá a nic neresetuje, takže lze jednu konverzaci ukončit a druhou začít, aniž by okno mezitím probliklo.

Pokud chcete okno vrátit do nové konverzace jedním krokem, použijte místo toho restart().

`setUserToken(userToken)`¶

Zastaralé. Původní název metody startDiscussion(userToken), na kterou nyní přeposílá. Volání zapíše varování do konzole.

`logout()`¶

await window.daktelaAiChat.logout();

Zneplatní session na serveru pro všechny karty i zařízení a tuto kartu přepne na anonymní identitu se smazanou lokální historií. Je určená pro okamžik, kdy se návštěvník odhlásí z vašeho webu.

Co záměrně nedělá:

Neukončí konverzaci. Diskuze zůstane otevřená a v přepisu je označená poznámkou. Návštěvník v ní nemůže pokračovat anonymně, ale po opětovném přihlášení se k ní vrátí.
Nezapomene prohlížeč. Další anonymní návštěva je rozpoznána jako tentýž prohlížeč, který v té době už nevlastní nic z přihlášeného účtu.

Jazyk¶

`setLanguage(languageCode)`¶

Přepne jazyk rozhraní. languageCode je dvoupísmenný ISO kód jazyka — en, cs, sk a tak dál.

Kód musí patřit některému z jazyků povolených pro widget (configuration.languages.enabledLanguages) — jinak volání skončí s chybou v konzoli a nic se nestane. Jazyky povolíte v administraci (detail chatovacího okna → Languages) a publikujete; widget totiž vždycky čte jen publikovanou konfiguraci. Na stejné obrazovce najdete i kód každého povoleného jazyka.

Note

setLanguage() očekává kódy jazyků malými písmeny, např. setLanguage('cs').

`resetLanguage()`¶

Zruší přepsání a vrátí se k nastavené detekci.

Kontext konverzace¶

Kontext je sada dvojic klíč/hodnota, které bot umí číst — číslo objednávky, tarif, velikost košíku.

Klíče musí vypadat přesně tak, jak si je pojmenovává bot platforma: $ na začátku a za ním jedno slovo bez mezer — tedy $orderId, ne orderId ani $order id. Klíč, který tomuhle neodpovídá, se zahodí i s chybou v konzoli — bot by ho stejně nikdy nedokázal vyhodnotit.

V záložce Options v administraci si můžete přednastavit dvojice kontextu. Ty se použijí v každé diskuzi, kterou widget založí, včetně té po restartu — fungují jako výchozí hodnoty. Voláním addContext() / setContext() z vaší stránky přepíšete stejný klíč jen pro aktuální diskuzi.

`addContext(context)`¶

window.daktelaAiChat.addContext({
  $orderId: 'A-1234',
  $plan: 'premium',
  $note: { value: 'expires soon', lifespan: 3 },
});

Přijímá normální objekt. Skalární hodnoty se automaticky zabalí; přes { value, lifespan } můžete omezit, kolik odpovědí bota daný záznam přežije. Klíče se slučují, ne přepisují. Pokud zrovna běží konverzace, odešle se to hned, jinak se to přiřadí k té další. Klíče, které nesplňují pravidlo $name, se přeskočí — zbytek objektu se přesto použije.

`setContext(key, value)`¶

Zkrácená forma addContext pro jednu hodnotu. Platí pro ni stejné pravidlo $name.

Vzhled¶

`setCustomCss(cssText)` / `resetCustomCss()`¶

Vloží vlastní CSS přímo do Shadow DOM widgetu. Projeví se, až se načte celý balíček.

window.daktelaAiChat.setCustomCss('.daktela-ai-window { border-radius: 37px !important; }');

Dvě věci, na které si dát pozor — obě jsou nejčastější příčinou pocitu „nic se nestalo":

Vlastní CSS se vkládá před vlastní stylesheet widgetu, takže pravidla skoro vždy potřebují !important.
Selektory musí sedět na skutečné třídy. Nejužitečnější jsou .daktela-ai-window, .daktela-ai-header, .daktela-ai-launcher-button, .daktela-ai-message-button a .daktela-ai-home-screen.

Widget při každém použití vlastního CSS zaloguje varování. To je záměr — názvy tříd se můžou kdykoli změnit, takže po každé aktualizaci widgetu si vlastní CSS znovu otestujte.

Nástroje pro akce na stránce¶

Agent modul — LLM, který řídí vaše dialogy — umí kromě promptu využívat i nástroje. Jedním typem jsou API Integrace, které volají vaše backendové endpointy. Nástroje pro akce na stránce jsou druhý typ: JavaScript funkce běžící přímo ve vaší stránce, kterou zaregistrujete pomocí registerTool() — Agent tak umí zavolat zpět do vašeho webu (vyhledat objednávku, zvýraznit prvek, otevřít tiket), aniž by data kdy opustila prohlížeč návštěvníka.

`registerTool(tool)`¶

window.daktelaAiChat.registerTool({
  name: 'openTicket',
  description: 'Opens a support ticket and returns its id.',
  parameters: {
    type: 'object',
    properties: { subject: { type: 'string' } },
    required: ['subject'],
  },
  confirm: true,
  handler: (args) => ({ ticketId: createTicket(args.subject) }),
});

Pole	Typ	Poznámky
`name`	`string`	Unikátní; opětovná registrace stejného jména nástroj nahradí.
`description`	`string`	Podle tohohle popisu se asistent rozhoduje, kdy nástroj zavolat.
`parameters`	JSON Schema	Schéma objektu. Validuje se jen `required` na nejvyšší úrovni a primitivní typy.
`handler`	`(args) => unknown`	Sync nebo async funkce. Nikdy neopustí prohlížeč.
`confirm`	`boolean`	Volitelné. Před spuštěním zobrazí výzvu ke schválení/odmítnutí.

Handler může vrátit libovolnou hodnotu serializovatelnou do JSON; ta se pošle zpátky asistentovi. Chyby se hlásí jako handler_error, handler, který přesáhne 30 sekund, jako timeout, a odmítnutá výzva jako user_declined.

Časování: aktuální sada registrovaných nástrojů se posílá s každou odchozí zprávou návštěvníka, ne s úvodním handshake. Nástroje registrujte dřív, než návštěvník odešle první zprávu — úvodní tah bota je totiž nevidí.

Info

Zaregistrování nástroje ho zpřístupní Agentovi, ale samo o sobě mu neřekne, kdy ho použít. Stejně jako u API Integrací musíte nástroj (podle jeho name) zmínit přímo v Instrukcích pro Agent — např. „Použij nástroj openTicket, když si zákazník přeje otevřít tiket podpory."

`unregisterTool(name)` / `getRegisteredTools()`¶

getRegisteredTools() vrátí schémata, která jsou momentálně platná (bez handlerů) — přesně to, co se posílá s odchozí zprávou.

Starší vlastní eventy `ew-*`¶

Existují jen z jednoho důvodu — aby stránky, které už měly integrované staré chatovací okno, fungovaly i po upgradu beze změny kódu. Názvy eventů, payloady i efekty odpovídají starému widgetu.

Pro cokoli nového použijte JavaScript API výše — je to oficiálně podporované rozhraní, pokrývá toho víc a umí hlásit chyby. Tyhle eventy jsou tu jen kvůli zpětné kompatibilitě.

Vyvolávejte je na window:

window.dispatchEvent(new CustomEvent('ew-open-window'));

Event	Efekt	Ekvivalent v API
`ew-open-window`	Otevře okno	`open()`
`ew-hide-window`	Schová okno, aniž by ukončil konverzaci	—
`ew-toggle-window`	Otevře nebo schová	—
`ew-end-discussion`	Ukončí konverzaci na serveru, aby se asistent mohl rozloučit a požádat o hodnocení; okno zůstane otevřené. Když ho vyvoláte znovu po skončení konverzace, okno se zavře a začne nová.	—
`ew-reset-chat`	Začne novou konverzaci, stav okna se nemění	`restart()`
`ew-close-and-reset-chat`	Zavře okno a začne novou konverzaci	`restartAndClose()`
`add-context`	Jedna položka kontextu, `detail: { key, value }`	`setContext(key, value)`
`chatbot-ew-context-set`	Celý objekt kontextu v `detail`	`addContext(object)`
`ew-set-dark-mode`	Vynutí tmavý motiv	—
`ew-set-light-mode`	Vynutí světlý motiv	—
`ew-set-system-theme-mode`	Řídí se motivem operačního systému	—
`ew-enable-ga` / `ew-disable-ga`	Přepíná reportování do Google Analytics. `ew-disable-ga` zastaví jenom Google Analytics — Google Tag Manager pořád dostává eventy, stejně jako u starého widgetu.	—

Veřejné JavaScript API¶

Instalace¶

Jak funguje načítání¶

Ovládání okna¶

open()¶

close()¶

restart(options?) / restartAndOpen(options?)¶

restartAndClose()¶

destroy()¶

Identita¶

authorize(jwt, refreshJwt?)¶

startDiscussion(userToken?)¶

finishDiscussion()¶

setUserToken(userToken)¶

logout()¶