Messaging protocol

How the page and the extension communicate (you usually do not need to write this by hand).
Docs updated: 2025-12-17

Overview

RTO uses window.postMessage to exchange messages between your page and the extension. The helper RTO_form_api.js handles:

  • Generating requestId values
  • Waiting for the matching *Result message
  • Timeouts (TIMEOUT)
Recommendation
Use RTO_form_api.js unless you are building your own wrapper.

Message envelope

Outgoing messages usually contain:

  • origin: should be "rto-page"
  • type: for example "detect", "openTab", or "command"
  • requestId: unique ID to match replies

The extension responds with type + "Result" (example: detectResult).

Raw detect example

// Raw detect (without RTO_form_api.js)
(function(){
  const requestId = "detect_" + Date.now();
  window.addEventListener("message", function onMsg(ev){
    const d = ev.data;
    if(!d || d.requestId !== requestId) return;
    if(d.type !== "detectResult") return;

    window.removeEventListener("message", onMsg);
    console.log("detect result:", d);
  });

  window.postMessage({
    origin: "rto-page",
    type: "detect",
    requestId
  }, "*");
})();

Raw command example

DOM actions are sent as type:"command" with an action name and a payload object.

// Raw command (example: getText)
(function(){
  const requestId = "cmd_" + Date.now();
  window.addEventListener("message", function onMsg(ev){
    const d = ev.data;
    if(!d || d.requestId !== requestId) return;
    if(d.type !== "commandResult") return;

    window.removeEventListener("message", onMsg);
    console.log("command result:", d);
  });

  window.postMessage({
    origin: "rto-page",
    type: "command",
    requestId,
    action: "getText",
    payload: {
      tabKey: "demoTab",
      selector: "h1"
    }
  }, "*");
})();
Note
Even if you write raw messages, you still need allow-list permission and a controlled tab for most actions.

Next