tiketoChat API

window.tiketoChat is a command function. A small stub queues commands before the async loader arrives; the loader replaces it and replays the queue in order. Register a handler before the agent can call it. Registration after init is supported, but an earlier call cannot be replayed.

TypeScript declarations

Since v0.3.0, each published embed includes declarations generated from the same core contracts as the catalogs. Download the declaration for the exact immutable loader version you use—for example /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/demo names in the catalog. Names supplied specifically for your chatbot also work through string-typed fallback overloads. For strong client-specific types, 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
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 self-hosted widget, and launches it with a snapshot of the accumulated context. Call it once. It deliberately remains fire-and-forget so it is safe in the preload queue. The legacy { client, env } object is rejected, logged as an error, and makes no config request.

on and off

Since v0.3.0. Use events when your page needs an observable result. Queue them before init, and retain 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);
}
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 every successful initial launch and reset({ relaunch: true }). It is sticky: a handler first registered after the widget is ready is called asynchronously once. error receives each initialization, destruction, or explicit relaunch failure and is sticky in the same way: a late handler receives the last error asynchronously once. The remembered error is cleared by the next successful ready. Registering the same event/handler pair repeatedly does not duplicate it. The loader also writes initialization and queued-command failures to the console with a [tiketoChat] prefix. Call cleanupChatEvents() from your SPA teardown.

context

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

Shallow-merges non-sensitive values for the next launch. Context is read as a snapshot when the widget launches; later calls do not mutate the running agent session. They apply after reset({ relaunch: true }) or on the next page load. Context is not a secret channel and is not automatically assigned to agent project variables.

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. Agent-provided 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/asynchronous host handler by name. The embed validates both the incoming payload and returned result against the enabled versioned contract. Late registration is supported as long as it happens before the agent emits that action.

component

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

Registers or replaces a host renderer. It receives the widget-owned mount element, validated payload, and a reply API. It may return a cleanup function. Register before the response is rendered; a response restored from history before your renderer mounts shows fallback text.

reset

Since v0.3.0. Clears the conversation boundary for logout/account switching and returns a promise. With no options, reset destroys an active widget, clears its data, and leaves it stopped—no new conversation or usage is created.

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 });

Use the same sequence to start chat for a newly signed-in user after logout without reloading the page. init is called once per page; do not call it again for the new user.

For an active client, reset requires the widget’s destroy() operation to succeed. It always removes that project’s persisted Voiceflow conversation from local and session storage and clears replied request IDs; if destruction is missing or fails, the promise rejects and no relaunch occurs. Before any successful initialization, it removes all widget-owned voiceflow-session-* keys from both storage areas.

Concurrent calls with the same options share the same scheduled reset. A call with different options waits for the earlier reset and then runs, so reset() followed by reset({ relaunch: true }) finishes with a clean relaunched widget. A failure after { relaunch: true } emits error and rejects the promise. The default logout path has no relaunch step. Reset does not clear host application state.

The preload queue can run a reset, but the GA-style stub cannot return the loader’s eventual promise: await tiketoChat("reset") is meaningful only after the loader is ready. Use the ready event (or your own loader-ready check) before an awaited reset. A queued reset failure is sent 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 agent; 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.