Actions with Results

Declare the action in customActions. Validate input data and user permissions in the handler and on the server; keep website confirmation for significant changes.

Declare the Handler

Set returnsResult: true to pass the handler result to the agent for its answer. For example, this can answer the question “How many subscribers does bot 15 have?”:

SenlerWidget.init({
  channel_id: "xxx",
  customActionsLanguage: "en",
  customActions: {
    "site.getSubscriberCount": {
      title: "Subscriber count",
      description: "Returns the current subscriber count for a bot by bot_id.",
      returnsResult: true,
      payloadSchema: {
        type: "object",
        properties: { bot_id: { type: "integer", minimum: 1 } },
        required: ["bot_id"],
        additionalProperties: false,
      },
      async handler({ payload, signal }) {
        const subscribers = await getSubscriberCount(payload.bot_id, { signal });
        return { bot_id: payload.bot_id, subscribers };
      },
    },
  },
});

getSubscriberCount is your data-reading function that checks the current user's permissions. Implement it on the site and pass signal to the network request to support cancellation.

Invocation and Result

In this mode, the agent invokes the action through the execute_widget_custom_action tool. Neither a button nor autoExecuteCustomActionNames is required; an action with this flag cannot be used as a button. The handler receives { name, payload, signal }. Return a value or a Promise: the widget waits for the result and sends it to the model as a tool response. Data is saved in the dialog history, so return only what the answer needs, without access tokens or secrets.

Return JSON: an object, array, string, finite number, boolean, or explicit null. Values 0 and false are preserved. undefined, functions, DOM elements, circular structures, and other non-JSON values are errors. The maximum size is 16 KiB UTF-8, depth is 8 levels, and total number of values is 2048. A thrown error or rejected Promise is sent to the agent as a tool error.

Waiting and Cancellation

The handler wait is limited to 20 seconds; the overall call including delivery has a 30-second deadline. On timeout or widget destruction, signal is aborted; stopping the operation itself depends on whether your code supports it. A late result does not replace a completed call. Heavy synchronous code can still block the page: a timer cannot interrupt JavaScript.

Each call belongs to the handler instance on the page that declared the action. Another tab, a page reload, or a replacement action definition cannot take over an old call. If the original page is no longer available, a timeout is returned to the agent. Redelivering a request or result does not execute the handler again. An error or timeout does not prove that the site operation did not run.

Waiting is added only for actions with returnsResult: true: handler execution, result delivery, and the model's next step. A Promise itself does not block the interface. Return concise data to limit context size and response processing time.