Host actions

Use the built-in MCP integration for remote tools that need the signed-in user’s browser credentials.

A host action is a named request from the chatbot to your page. Tiketo supplies its name and input and output schemas. Your code registers the matching handler.

The handler receives validated input and returns the declared output, either directly or as a promise. Register it before the chatbot can request the action. Registration may happen after init if the action cannot run first.

Read page state: whereAmI

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

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

The reference integration returns only location.pathname, such as /checkout. Query strings and hashes can contain search terms, tokens, filters, or private state. Include them only when Tiketo has added them to your route contract and your team has reviewed the data.

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

Apply the validated request and return what actually happened. Throw an Error if the effect fails.

Failure behavior

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

Side effects and idempotency

One matching request causes one handler call in the current page session. This is not an exactly-once business transaction. Reloads, retries, or later conversation paths can request the effect again. Authorize purchases, reservations, account changes, and other sensitive effects on your backend. Use a domain idempotency key instead of relying on the public client ID or chat session.

Keep handlers quick and deterministic. Bound any returned promise and show a host-side failure state when useful. Handler results and thrown error messages reach the conversation, so never put secrets in them. See Security and CSP for data-handling rules.