Action Buttons

First, declare the custom action and its input data.

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, payloadSchema, and returnsResult.

The name, title, description, data schema, and result-return flag 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.

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.

If returnsResult is omitted or false, the loader does not await a returned Promise or send the return value to the agent. In this mode, catch asynchronous failures yourself and display the result in the site interface.

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.

URL Navigation

open_url is the built-in action type for a link button in an agent reply. For example, the agent offers a "View pricing" button, and the visitor clicks it to open the pricing page.

To let the agent add these buttons, enable buttons in replies. You do not need to declare open_url in customActions or write a handler for it: the widget handles navigation.

In the button's action definition, url contains the address and target determines where it opens:

• target: "blank" or an omitted target: in a new tab;
• target: "self": replacing the current website page, not inside the chat window.

These are button action parameters, not SenlerWidget.init settings.

For an ordinary link to your own or another website, open_url is sufficient. Use custom_action when navigation needs additional logic or the application should open a section without reloading the page. For example, your handler can validate the payload and open an order through the application router, as in the action declaration example.