Esta página se publica en inglés y en ucraniano; abajo está la versión en inglés.
Page actions: what the assistant can do on a page
For developers, in code: what the assistant can do on a page, what it never does on its own, and the three switches that govern it.
With page actions on, the assistant can read the screen the visitor is on, fill in forms and press buttons — on a website or inside an application. It works from the page itself: labels, roles, ARIA attributes, the things a screen reader already uses. Markup is optional and makes it better; it is never required to start.
In the panel: Widget → Page actions → Let the agent act on the page (Widget settings).
Read is not act
The widget scans the page into a manifest: every visible control with its kind, its name, whether it is filled, whether it is disabled, which set it belongs to. That is what the assistant reads to answer «what is this field?» or «why is Save greyed out?». A fill or a press is an act, and a control can be readable without being actionable.
The manifest carries state, not content: filled is a boolean. What is typed in a field
leaves the browser only under the owner’s page_read_values switch, and passwords, hidden fields,
file inputs and anything marked data-sa-private never do.
Reading the screen.
What runs at once, and what is held
- Data entry runs at once, however many fields: typing into a field, picking an option, ticking a box. The visitor sees the real text land on their own screen and can undo it with a reload. A fill onto a field that already had text is reported as replaced; a fill that landed on the value already there is reported as unchanged.
- A consequential press is held. Send, Save, Order, Delete — anything that cannot be undone — is never pressed on the assistant’s own initiative. When it comes bundled with data entry, the assistant applies the entry, then asks, naming the button, and presses only on a yes.
- A press that changes only the view runs at once: a tab, a segment of a segmented control,
an ARIA
optionorradio, a disclosure (aria-expanded). These change what is being edited, not the world. Consent and commit. - A press given as its own command runs at once. «Send it» is the visitor pressing the button through the assistant.
The three switches
All three are the owner’s, on the widget’s Page actions tab in the panel; none is set from the page.
| Switch | Values | Meaning |
|---|---|---|
| Let the agent act on the page | on / off | the feature; off = the assistant answers and navigates but touches nothing |
Button clicks (page_actions_submit_policy) |
off / confirm / auto |
Fill only (never click) · Click with confirmation: hold a bundled press and ask (the default) · Save automatically: press the marked commit control after a landed batch, no question |
Can the assistant see what is in the fields (page_read_values) |
off / marked / all |
Never — only whether it is filled (the default) · Only fields marked data-sa-read · Every field on the page |
A host page can switch page actions off for one page load with
Shukai.setPageActions(false) — never persisted, never able to turn on what the owner turned off.
JavaScript API.
Page actions are a feature of the Growth plan and above. On a plan without them the assistant does not offer to act on the page and the widget is served with them off.
What the assistant can do, in one list
| Op | On | Notes |
|---|---|---|
fill |
text fields, textareas, sliders (a number), comboboxes | replaces the value; reported replaced / unchanged |
append |
text fields, textareas | adds to the end in the browser — the existing text never leaves the page, so it works with reading off; refused on a dropdown |
select |
native <select>, ARIA comboboxes |
matches the option by its visible label, exact then contains |
check |
checkboxes, radios, ARIA checked |
sets a tick; on a self-saving switch marked data-sa-commit it is treated as a press |
click |
buttons, links, tabs, options, disclosures | held when consequential; inline when a choice |
| scroll to a place | headings, sections, named landmarks | «show me where that is» — works even with actions off |
| scroll the page | the document or a declared container | «scroll down» — one screen at a time |
Three rules you cannot see in the DOM
- Ids are stable. A control without
data-sa-idgets a generated id that is remembered per element, so inserting a row above it does not renumber it. - Invisible controls are not on the screen. Anything hidden by CSS is skipped — a page that renders the same switcher for desktop and for mobile offers only the visible one.
- The page follows the action. After a step the changed element scrolls into view (once per batch, to the first step that succeeded) and takes focus — unless the visitor is typing in the chat.
Where to go next
- A form, step by step — the demo form on our own site, marked up and explained line by line.
- Marking up controls — ids, names, hints, groups, private regions.
- Consent and commit —
data-sa-risk,data-sa-commit, the three policies. - Lists and variants — repeated rows and language switchers.
- Sliders and choices, Reading the screen, App screens.