Widget Custom Actions

Use customActions when a widget answer needs a button handled by your site: open an order, show a plan, start a custom flow, or change local interface state. Implement and secure the site-side action first, then declare it to the widget.

There is no separate customActions form in the cabinet. The site supplies them through SenlerWidget.init(...) or later through SenlerWidget.updateRuntime(...). This page therefore provides an integration example; Widget Interface shows how the visitor-facing button appears.

What Happens After the Answer

The page passes a customActions object. Each key is a technical action name. Each value has a required handler and optional title, description, and payloadSchema.

Only the name, title, description, and data schema are sent to the agent. The handler stays on the page. By default, it runs after the visitor clicks the custom_action button and receives { name, payload, button_text }.

Declare the Action

SenlerWidget.init({
  channel_id: "xxx",
  customActionsLanguage: "en",
  customActions: {
    "site.openOrder": {
      title: "Open order",
      description: "Opens an order card by order_id.",
      payloadSchema: {
        type: "object",
        properties: {
          order_id: { type: "string" },
        },
        required: ["order_id"],
        additionalProperties: false,
      },
      handler({ payload }) {
        const orderId = String(payload?.order_id || "");
        if (!canViewOrder(orderId)) return;
        openOrder(orderId);
      },
    },
  },
});

canViewOrder and openOrder stand for your site's access-check and navigation functions. Implement them in the site code; the loader does not create globals with those names.

When title and description are written in one language, set customActionsLanguage to "ru" or "en". It does not translate text; it tells AI which language the descriptions use. Without it, bilingual Russian and English search is used.

Describe Input Data

The action name comes from the customActions object key. It must start with a Latin letter, be no more than 120 characters long, and may contain Latin letters, digits, _, ., :, and -.

One context can declare up to 20 actions. title is limited to 80 characters and description to 240. payloadSchema itself must be a plain schema object. Its root type may be omitted; if present, only "object" is supported. Schema depth is limited to 8 levels, one serialized schema to 1200 characters, and all action descriptors combined to 6000 characters. The combined limit includes names, titles, descriptions, and schemas.

A limited JSON Schema subset is supported: types object, string, number, integer, boolean, array, and null, plus properties, required, additionalProperties, items, enum, title, description, default, examples, minLength, maxLength, pattern, minimum, maximum, minItems, and maxItems. Other fields are rejected during initialization. Never place secrets in a schema, description, or payload.

Do not generate custom_action.name dynamically: the agent uses only names explicitly passed by the current page. If the page did not declare an action, the widget must not promise or execute that button.

Validate the Action on the Site

payload is derived from the agent response and reaches the browser with the button, so treat it as untrusted input. The handler must validate types, user access, object existence, and whether the operation is allowed. Keep the site's normal confirmation for deletion, payment, and other significant changes.

The loader invokes handler synchronously and does not await a returned Promise. For asynchronous work, catch failures yourself and display the result in the site interface.

Replace actions without recreating the widget:

SenlerWidget.updateRuntime({
  customActions: buildActionsForCurrentPage(),
  customActionsLanguage: "en",
});

The loader passes new descriptions to the widget. Each handler stays on the site page and replaces the previous handler with the same name.

updateRuntime replaces the complete current action set. Pass the complete set for the new page, not only newly added names.

Automatic execution

By default, an action is presented as a user-facing button. autoExecuteCustomActionNames allows only the listed names to execute automatically in the current runtime scenario. These buttons are hidden from the message. Only the first matching action in one response is executed automatically, so design that response around one automatic operation; other listed buttons are hidden as well.

Do not assume the permission persists after switching dialogs or starting a new scenario. Pass the smallest list again only where automatic execution is required, and do not use it for irreversible actions or actions that require confirmation.

Difference from Element Actions

A custom action declares a site business operation and invokes your handler. Element actions such as highlight, click, and fill work with marked DOM targets by data-ai-context-id. Do not create a custom action only to highlight an ordinary button.

The site page handles open_url: target: "self" changes the current page, while a link without self opens in a new tab.

Prefer a custom_action for internal site navigation so the site can validate the payload and use its own router.

What to Add Next

If an action must prepare an AI edit for a specific field and let the user review it before application, use inline edits. The Public API reference contains the complete runtime-parameter and event lists.