Page actions

Register a host action#

Page actions let the website open its own UI or navigate to an approved page. Install the current embed, then run registration after the script has loaded. Keep handlers in your application; the agent receives their names, descriptions and parameter definitions, never the handler code.

MakeAgentFast.registerAction("show_details", {
  description: "Show the details section on this page",
  params: { section: { type: "string", description: "Use delivery or returns" } },
  confirm: true
}, async ({ section }) => {
  const sections = {
    delivery: document.getElementById("delivery-details"),
    returns: document.getElementById("returns-details")
  };
  if (!Object.hasOwn(sections, section) || !sections[section]) {
    throw new Error("Unknown section");
  }
  sections[section].scrollIntoView({ block: "start" });
  return { shown: section };
});

// Run when the page component unmounts:
// MakeAgentFast.unregisterAction("show_details");

Both methods return a boolean indicating whether registration/removal was accepted. Names use lowercase letters, digits and underscores, start with a letter and contain 2–40 characters. There are nine custom registration slots plus built-in open_page. Each definition allows five string parameters; all declared parameters are required, with values up to 200 characters. Descriptions are limited to 200 characters. A handler may return a string or JSON-serializable value up to 2 KB within 10 seconds.

Approve actions in the dashboard#

Open the installed website so it reports its action names and descriptions, then open Agent → Actions → Page actions. Enable the feature and allow each intended action. Reported descriptions are untrusted website metadata; discovery does not approve anything. Settings autosave.

The agent can propose only actions that are both currently registered and allowed. The customer sees a card before execution. Confirmation is required unless the owner marks the action safe; confirm: true in host code always requires a tap. confirm: false alone does not bypass the owner's policy. Reserve safe mode for harmless UI changes.

Built-in open_page needs no handler. Allow it in the dashboard; it accepts a relative path or HTTP(S) URL on the agent's allowed website origins. Relative paths also require the current website origin to be allowed. It cannot navigate to an arbitrary external destination.

Report an event with track#

MakeAgentFast.track("form_error", { formId: "contact" });
MakeAgentFast.track("checkout_help", { step: "delivery" });

Call these after the embed loads and the corresponding event actually occurs. Configure a matching event name in Follow-ups. Names follow the same 2–40-character format; optional data must be a JSON object of at most 1 KB. Do not send field values, credentials or payment details. Rules match event/path/delay; metadata is not stored, sent to the model or used as a conversion claim. A true return means the loader accepted the event, not that a message was displayed.

Safety and verification#

Page actions work in the live website widget, not messaging channels, owner rehearsal or live voice. The loader and frame check origin, source, slug and pending request IDs. Results return to chat as untrusted browser data, not proof that a server record changed. Keep authentication and authorization in your own handlers/backend; use Change actions for consequential business writes.

A timeout does not cancel the handler or prove that nothing happened. Do not automatically retry an uncertain action. Unregister handlers when their page component leaves the screen. Existing cached embeds need the current loader version, 20261014-page-actions, for this API.

This API does not handle payments or provide a Shopify connector.