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¶

Na stránku vložte oba skripty ve stejném pořadí, v jakém jsou napsané níže.

<script>
  // Fronta příkazů: umožňuje stránce volat API dřív, než se widget vůbec načte.
  (function () {
    if (window.daktelaAiChat && window.daktelaAiChat.__isProxy) return;
    var q = [];
    window.daktelaAiChat = new Proxy(
      { queue: q, __isProxy: true },
      {
        get: function (t, p) {
          if (p in t) return t[p];
          return function () {
            q.push({ m: p, a: [].slice.call(arguments), t: Date.now() });
          };
        },
      },
    );
  })();
</script>

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

<script
  defer
  crossorigin="anonymous"
  src="https://my-instance.bot.coworkers.ai/chat-window-public-api/loader/dai-loader.js"
></script>

url a doména v src musí patřit stejné instanci.

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í.

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.

Jazyk¶

`setLanguage(languageCode)`¶

Přepne jazyk rozhraní.

Kód musí být uvedený v 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.

`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()¶

Jazyk¶

setLanguage(languageCode)¶

resetLanguage()¶