RTO_form_api.js

Core helper (recommended). Promise-based wrapper around the RTO postMessage protocol.
Docs updated: 2025-12-17

What it is

RTO_form_api.js is the foundation helper used by the documentation and most sample projects. It hides the raw window.postMessage protocol and gives you a clean async API: detect the extension, open and control tabs (by tabKey), and send predefined commands.

All methods return a Promise. Failures are normalized to an object like { code, message }.

Requirements

  • The RTO extension must be installed and enabled.
  • Your admin page origin must be allowed in the extension Allow-list.
  • Any target host you want to open or automate must also be allow-listed.
Best practice: always gate your UI with RTOForm.detect(1500). If detection fails, show a friendly “install / enable / allow-list this site” message.

Download

Download RTO_form_api.js

Minimal usage

This is the smallest “copy/paste” snippet that reliably works: detect the extension, then open a controlled tab using a stable tabKey. 

<script src="../RTO_helpers/RTO_form_api.js"></script>
<script>
(async function () {
  try {
    // detect(timeoutMs:number)
    await RTOForm.detect(1500);

    await RTOForm.openTab(
      { tabKey: "demo", url: "https://example.com", focus: true, newTab: true },
      { timeoutMs: 20000 }
    );

  } catch (e) {
    console.error("RTO error:", e && e.code, e && e.message);
  }
})();
</script>
Note: RTOForm.openTab() in this helper forwards only url, focus and newTab. If you need additional fields supported by the extension, use send() (see below).

Optional configuration

Set these globals before loading RTO_form_api.js:

Global Type Default What it does
window.RTO_PAGE_ORIGIN string "rto-page" Value placed into outbound messages as origin (a string, not the browser origin).
window.RTO_STRICT_ORIGIN boolean false If true, only accepts responses where the payload origin string matches the extension origin string.
window.RTO_TABKEY string (empty) Default tabKey if you omit it in calls.
window.tabKey string (empty) Legacy fallback for tabKey.
This helper does not support a configurable RTO_EXT_ORIGIN global in v7.11.4 helpers.

API quick reference

Exports: window.RTOForm with these methods:

MethodPurposeTypical timeout
detect(timeoutMs)Fast check that the extension is listening.~1500ms
openTab(args, opts)Open/control a tab identified by tabKey.~20000ms
navigate(args, opts)Navigate an existing controlled tab.~20000ms
focusTab(args, opts)Bring the controlled tab to front.~5000ms
closeTab(args, opts)Close the controlled tab.~8000ms
listTabs()List controlled tabs (debug/UI).~8000ms
adoptTab(args, opts)Attach an existing tabId to a tabKey (advanced).~8000ms
command(msg, opts)Send a named predefined command (incl. advanced operations).~20000ms
send(type, payload, opts)Low-level: send any action type + payload.depends
bestEffort(promise, opts)Ignore selected errors for non-critical steps.n/a

Advanced: using send()

Use send() when you need to pass action-specific fields that are not forwarded by the convenience wrappers. (Example: an extension-level option like singleton if your extension supports it.) 

<script src="../RTO_helpers/RTO_form_api.js"></script>
<script>
(async function () {
  await RTOForm.detect(1500);

  // Low-level openTab with extra fields (if supported by the extension)
  await RTOForm.send(
    "openTab",
    { url: "https://example.com", focus: true, newTab: true, singleton: true },
    { tabKey: "demo", timeoutMs: 20000 }
  );
})();
</script>

Common errors

CodeMeaningTypical fix
EXT_NOT_DETECTED The extension did not respond. Check install/enable, then gate with detect() and show guidance.
DOMAIN_NOT_ALLOWED Target host is not allow-listed. Add the host in the extension Allow-list, then retry.
NO_CONTROLLED_TAB No tab is controlled for this tabKey. Call openTab() first (or adoptTab()), verify tabKey.
TIMEOUT No response within timeout. Increase timeoutMs, add bounded retries/backoff, confirm the tab finished loading.

Next