Host actions

A host action is a named request from the agent to your page. Tiketo configures the workflow and supplies the name plus input/output schema; your code registers the matching handler.

The handler receives the validated input object and returns the declared output either synchronously or as a promise. It runs only when the launched agent emits the matching action request. Register it before that can happen; late registration after init is otherwise supported.

Read page state: whereAmI

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

whereAmI@1 has an empty input and returns { route: string }.

Apply an effect: setFeature

tiketoChat("action", "setFeature", function (payload) {
  var darkMode = payload.feature === "darkMode";
  var target = darkMode ? document.body : document.querySelector("#featured-box");
  target.classList.toggle(
    darkMode ? "dark-mode" : "is-highlighted",
    payload.enabled,
  );
  return { feature: payload.feature, enabled: payload.enabled };
});

Use the validated payload, perform the effect, and return what actually happened. If the effect can fail, throw an Error rather than claiming success.

Failure behavior

• An invalid action payload does not call your handler. The embed warns and returns { ok: false, error } as the correlated result the agent is waiting for.
• If your handler throws or rejects, the embed catches it, warns, and sends a failure result to the agent.
• If the return value does not match the output schema, the embed warns and sends a validation failure.
• A failure while sending the result is contained so it does not break the widget.

Side effects and idempotency

One matching trace causes one handler call in the current page session. The trace transport is not an exactly-once business transaction: reloads, retries, or future agent paths can request the effect again. For purchases, reservations, account changes, or other sensitive effects, authorize on your backend and use a domain idempotency key. Do not rely on the public client ID or the chat session as authorization.

Handlers should be quick and deterministic. Keep a returned promise bounded, show host-side failure state where useful, and never return secrets to the agent.