tiketoChat API

window.tiketoChat is a command function. The snippet queues commands until the async loader is ready. The loader then replays them in order.

TypeScript declarations

Since v0.3.0, every published embed includes declarations generated from the same contracts as the catalogs. Download the declaration for your exact immutable loader version. For example, use /embed/v0.3.0/tiketo-chat.d.ts. Keep it in your source tree and reference that local copy:

/// <reference path="./vendor/tiketo-chat.d.ts" />

The file is not present in v0.1.0 or v0.2.0. Do not link declarations through /embed/stable/ until stable is v0.3.0 or newer, and never mix loader and declaration versions.

The generated file strongly types the shared and demo names in the catalog. Client-specific names still work through string-typed fallback overloads. To type them fully, merge them into the public interfaces:

export {};

declare global {
  interface TiketoHostActions {
    openBasket: {
      input: { basketId: string };
      output: { opened: boolean };
    };
  }
}

tiketoChat("action", "openBasket", ({ basketId }) => ({
  opened: basketId.length > 0,
}));

Command summary

Command	Arguments	Return
init	client ID	void
context	values	void
mcp	server key, options or null	void
action	name, handler	void
component	name, renderer	void
on	ready or error, handler	void
off	ready or error, same handler	void
reset	optional { relaunch }	Promise<void>

An unknown command is ignored and writes a [tiketoChat] Unknown command … ignored. warning. It never falls through to initialization.

on, off, and reset require v0.3.0 or newer. A v0.2.0 loader does not recognize this command API: it may misinterpret these calls as legacy initialization, while newer loaders warn about unknown commands. Upgrade the pinned loader and declarations together before using them.

init

tiketoChat("init", "TC-XXXXXXXX");

Fetches /config/<id>.json, loads the chat widget, and launches it with the accumulated context. Call it once per page. It returns nothing, so it is safe to use in the preload queue. The removed { client, env } form logs an error and makes no config request.

on and off

Since v0.3.0. Use events when your page needs to observe startup. Queue them before init, and keep the function references so an SPA can unregister them:

function handleChatReady() {
  document.documentElement.dataset.chatReady = "true";
}
function handleChatError(error) {
  console.error("Tiketo Chat did not start", error.code, error);
}
tiketoChat("on", "ready", handleChatReady);
tiketoChat("on", "error", handleChatError);
tiketoChat("init", "TC-XXXXXXXX");

function cleanupChatEvents() {
  tiketoChat("off", "ready", handleChatReady);
  tiketoChat("off", "error", handleChatError);
}

ready runs after the first successful launch and after each reset({ relaunch: true }). A late ready handler runs asynchronously once if the widget is already ready. error reports initialization, destruction, and relaunch failures. A late handler receives the last error asynchronously once, until a successful ready clears it. Registering the same event and handler pair more than once has no effect. The loader also writes initialization and queued-command failures to the console with a [tiketoChat] prefix.

The error is a TiketoChatError, which extends Error and adds a stable code. Branch on code; treat message and cause as diagnostics rather than stable text.

Code	Failed stage
config_failed	Downloading or reading /config/<id>.json
widget_failed	Downloading the loader’s self-hosted widget script, or the script not exposing its API
init_failed	Launching the downloaded widget
reset_failed	Destroying or clearing the current widget during reset
relaunch_failed	Any initialization stage requested by reset({ relaunch: true })

The first three codes apply to the initial init. Any relaunch failure becomes relaunch_failed. If loader.js never executes, it cannot replay the queued error registration. Monitor the script element’s error event or use your tag manager’s load monitoring for that request.

context

tiketoChat("context", {
  locale: document.documentElement.lang,
  pageTitle: document.title,
  route: location.pathname,
});

Shallow-merges values for the next launch. Context is a snapshot taken when the widget starts. Later calls do not change the running conversation; they apply after reset({ relaunch: true }) or on the next page load. Context is not automatically assigned to chatbot variables. Follow the security guidance when choosing its fields.

Since v0.3.0, the embed uses context.locale for its own labels: values beginning with cs select Czech; every other or missing value selects English. Chatbot questions, option labels, and fallbackText are not translated by the embed.

action

tiketoChat("action", "whereAmI", function () {
  return { route: location.pathname };
});

Registers or replaces a synchronous or asynchronous host handler by name. The embed validates the input and result against the enabled versioned contract. See Host actions for registration timing and failure behavior.

mcp

Registers, replaces, or removes browser authentication for one configured MCP server. The embed supplies the mcpCall handler itself; host code does not register it as an action. See MCP integration for the header-provider and cookie forms, CORS requirements, write confirmation, and logout handling.

component

tiketoChat("component", "productPreview", function (element, payload) {
  element.textContent = payload.name;
  return function cleanup() {
    element.replaceChildren();
  };
});

Registers or replaces a host renderer. It receives a widget-owned mount element, a validated payload, and a reply API. See Components for renderer timing, cleanup, and fallback behavior.

reset

Since v0.3.0. Use reset at logout or when the signed-in account changes. reset() destroys the active widget, clears its conversation data and replied request IDs, and leaves chat stopped. It does not clear your application state or start a new conversation.

For an account switch that should immediately start a clean widget, set the new public, non-sensitive context first and opt into relaunch:

tiketoChat("context", { accountTier: "member" });
await tiketoChat("reset", { relaunch: true });

This sequence also starts chat for a newly signed-in user without reloading the page. Keep init to one call per page.

Reset behavior:

• An active widget must be destroyed successfully. Reset still clears its persisted conversation from local and session storage if destruction fails, but the promise rejects and relaunch does not run.
• Before the first successful initialization, reset removes all widget-owned conversation storage keys from both storage areas.
• If reset fails during logout, hide the launcher, report reset_failed, and finish your application logout. The React example shows this containment flow.
• Concurrent calls with the same options share one reset. Calls with different options run in order. A relaunch failure emits error and rejects the promise.
• A queued reset cannot return its eventual promise through the preload stub. Wait for ready before awaiting reset. Queued failures go to error handlers and the console without an unhandled rejection.

Diagnostics

Recoverable failures are written to the browser console with a [tiketoChat] prefix. Initialization skipped commonly means a missing config, blocked origin, CSP, or network failure. Invalid actions return a structured failure to the chatbot; invalid components render fallback text.

Contract catalogs

• Generated action catalog
• Generated component catalog

The catalogs describe contracts shipped by this embed version. The exact action and component names enabled for your chatbot come from Tiketo.