Developer

Appearance

Iframe Messaging

Message types and payloads for integrating the rooomAvatars Editor via postMessage.

The parent window and the editor iframe communicate using window.postMessage. Initialization uses URL parameters and the #token=API_TOKEN hash fragment, not a postMessage handshake. See URL Parameters.

Overview ​

Pass the API token through the URL hash fragment and optional initial configuration through query parameters when you build the iframe src.

After the editor is running, the parent page can send rooom-avatars-config messages. The editor sends rooom-avatars-info, rooom-avatars-completed, and rooom-avatars-error messages back to the parent page.

Message envelope ​

Messages from the editor to the parent window use this envelope:

json
{ "type": "...", "source": "rooom-avatars", "data": { "...": "..." } }

The data key is only present when the message carries a payload.

Messages from the parent page to the editor use type and data.

json
{ "type": "rooom-avatars-config", "data": { "config": { "version": "1.0.0" } } }

Use the editor origin as the targetOrigin argument when you call postMessage.

Messages (iframe → parent) ​

All messages sent from the iframe include:

  • type: message type
  • source: always "rooom-avatars"
  • data: payload (present only when there is data to send)

INFO

Only rooom-avatars-completed is required to integrate the editor — it carries the final avatar ID and download URLs. rooom-avatars-info and rooom-avatars-error are optional and useful when your integration needs live previews of in-progress edits or wants to surface editor errors to the user.

rooom-avatars-info ​

Sent whenever the user changes the avatar configuration. Use it to track the current state before the user finishes.

Payload (data):

  • name (string): the current avatar name
  • config (object): current avatar settings JSON (see Configuration Schema)

rooom-avatars-completed ​

Sent when the user completes the editor flow and the avatar has been registered.

Payload (data):

  • name (string): the avatar name entered by the user
  • config (object): avatar settings JSON (see Configuration Schema)
  • avatarId (string): the registered avatar ID
  • modelUrl (string): URL to download the avatar .glb model
  • previewUrl (string): URL to download the avatar preview image

rooom-avatars-error ​

Sent when saving or export fails.

Payload (data):

  • message (string): error description

Messages (parent → iframe) ​

rooom-avatars-config ​

Send this to update the current avatar configuration at any time. If the editor has not finished initializing yet, the message is queued and applied automatically once initialization completes.

Payload (data):

  • config (object, required): avatar settings JSON (see Configuration Schema)
  • name (string, optional): new avatar name

Send a runtime configuration update to the iframe with a strict targetOrigin:

js
const iframe = document.getElementById('rooom-avatars');
const iframeOrigin = new URL(iframe.src).origin;

iframe.contentWindow?.postMessage(
  { type: 'rooom-avatars-config', data: { config: { version: '1.0.0' } } },
  iframeOrigin,
);

Security notes ​

When you receive messages from the iframe, validate these fields before using event.data:

  • event.origin matches the editor origin
  • event.source is the iframe contentWindow
  • event.data.source === "rooom-avatars"

Use this listener pattern for messages from the editor:

js
window.addEventListener('message', (event) => {
  if (event.origin !== iframeOrigin) return;
  if (event.source !== iframe.contentWindow) return;
  if (event.data?.source !== 'rooom-avatars') return;

  console.log(event.data.type, event.data.data);
});