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 (token, initial config) is handled via a URL fragment identifier and URL parameters, not via postMessage. See URL Parameters.

Overview ​

The editor does not use a postMessage handshake for initialization. Pass the API token through a URL fragment identifier (#token=YOUR_API_TOKEN) and optional initial config through URL parameters when constructing the iframe src (see URL Parameters).

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

Message envelope ​

Messages sent from the editor to the parent window have this shape:

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

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

Messages sent from the parent to the editor need type and data. The editor validates that the message originates from window.parent and, when possible, checks the parent origin.

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)

rooom-avatars-info ​

Sent whenever the user changes the avatar configuration. Use this to track the current state without waiting for the user to finish.

Payload (data):

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

TIP

This is the most important message for your integration. Listen for rooom-avatars-completed to receive the registered avatar ID and download URLs after the user finishes.

rooom-avatars-completed ​

Sent when the user clicks "done" 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

Security notes ​

When receiving messages from the iframe, validate:

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