Widget in an embedded page

Connect widget actions to an embedded application page so the assistant can find the relevant elements.

Actions in an embedded application

Regular pages only need element markup. For a separate application with its own interaction protocol, pass pageElementActions in init. This is a local website adapter, not an MCP tool; it cannot be changed through updateRuntime.

execute(payload) receives event_id, attempt_id, action, target or target_chain, and value for filling or selection. A target contains context_id, an optional role, and an entity_type/entity_id pair for a specific entity.
Return null if the target does not belong to the application: the loader will handle it. For your own target, return a result with the same event_id, attempt_id, and action, an executed_at timestamp, and a status of success, not_found, blocked, or failed. Include error_code and a clear error_message for a rejection.
execute supports a Promise result and must finish within 2.5 seconds. After an exception, invalid result, or timeout, the loader reports an error and does not retry through another executor. Never discard target constraints: return blocked if the application cannot select a specific entity.
clear(scope) clears adapter highlights: tool refers to agent guidance, selected to the user-selected element, and all to both. The loader clears highlights on a new action, guide dismissal, and instance destruction.

SenlerWidget.init({
  channel_id: "YOUR_CHANNEL_ID",
  pageElementActions: {
    async execute(payload) {
      const target = payload.target ?? payload.target_chain.at(-1);
      if (!target?.context_id.startsWith("my-app.")) return null;
      return appBridge.execute(payload);
    },
    clear(scope) {
      appBridge.clearHighlights(scope);
    },
  },
});

The application developer implements appBridge; it is not a Senler method. Its execute must preserve the complete target and return the result format described above. Do not add a second PAGE_ELEMENT_ACTION listener alongside it: the loader already accepts the command and sends its result.

When forwarding an action to child iframes, the loader waits for one frame's response before contacting the next. Only not_found allows the search to continue; success, rejection, or failure ends the attempt. The child-frame search has a total timeout of 2.5 seconds. If the current frame has not replied by then, the result is failed with child_frame_action_timeout, without repeating the action in another frame. A timeout does not prove that the action did not happen: check the application state before retrying.

Preparing the page for highlighting

The optional pageElementActions.navigate(payload, { element, signal, execute }) handler prepares the website interface before Show on page, for example by collapsing a panel that covers the target. It runs only for highlight and scroll_to with user_initiated: true, not for automatic agent commands, clicks, or field input.

element contains the element found before preparation, or null. After changing the interface, call execute() and return its result: the loader looks up the target again in the updated layout. Repeated calls to this function within one attempt return the same Promise and do not duplicate the action. Use signal to stop preparation when the request is cancelled; do not highlight the saved element yourself.