Widget Custom Actions

customActions declare actions your site performs: open an order, show a plan, start a custom flow, or retrieve data for the agent's answer. By default, an action runs through a button. The returnsResult: true flag allows the agent to invoke the handler as a tool and receive its result. 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.registerAction(name, definition). This page therefore provides an integration example; Widget Interface shows how the visitor-facing button appears.

The handler runs in the browser on the open page. A token stored in localStorage is not added to requests automatically: the handler must explicitly supply the required header; cookies depend on the request origin and credentials setting. If the agent should call an installed MCP with a user token through server integration, use website user authorization for MCP.

Choose an Execution Mode

• Action buttons: the visitor clicks a button and the website runs the handler.
• Actions with results: the agent invokes the handler as a tool and receives JSON for its reply.

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.

To let the agent add buttons, enable creating buttons in replies for that agent. An action with returnsResult: true does not require this setting: it becomes available in a widget conversation when the site supplies its definition. Manage website elements through the widget controls page-element operations, not your customActions.

Updating Actions During Navigation

Register page actions without recreating the widget:

const unregister = SenlerWidget.registerAction("openProduct", {
  description: "Open a product by ID",
  payloadSchema: {
    type: "object",
    properties: { productId: { type: "string" } },
    required: ["productId"],
  },
  handler: ({ payload }) => openProductAfterValidation(payload),
});
SenlerWidget.configure({ customActionsLanguage: "en" });
// When leaving the page:
unregister();

openProductAfterValidation represents authorization checks and navigation implemented by your site. Descriptions reach the agent; handler stays in the browser.

The method returns a function that removes only this registration. A duplicate name produces an error: remove the previous registration before adding another one. Other actions stay available.

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.

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.