Roomstyler Editor

This document serves to be an introduction to embedding the Roomstyler Editor into your webpage. The Editor provides features for logging in as a certain user, opening a specific room and setting a language. How this is done will be explained in the following sections.

Table of contents



The url to the editor that you can embed is

tokennoA token obtained the roomstyler API, if Invalid or missing it will be ignored and an anonymous session will be initialized in the editor.

NOTE: If a token is supplied, it will be invalidated and can no longer be used in following calls. A new token will have to be generated.

This is done so that two users won't be able to log in using the same token.
room_urlnoA room url as seen in a room (check success tab)
langnoDefault: en, other options include: de, es, fr and nl

HTML snippet

The editor can be embedded through the use of an iframe.

<!DOCTYPE html>
        <title>Roomstyler Editor embed demo</title>
        <iframe src=""
                frameborder="0" width="1024"


Safari doesn't accept third party cookies by default unless you've visited a website and got a cookie before, because of this the editor might not work correctly. To fix this issue, we've created an endpoint that will set a cookie in the users browser and redirect them to a target endpoint specified by you.

The URL endpoint for this is

redirect_urlyesThe target page url

If the redirect_url parameter isn't set or no HTTP referer then a response with status 422 and an empty body will be rendered however the cookie will still be set in this case, the only difference is that no redirect will be executed to a target page.

So instead of sending the user directly to the editor from your own page, send it through first and set a redirect_url parameter to the target page that embeds the editor.

So if the link to the embedded editor first looked like this:

<a href="">

You would now change it to be:

<a href="">

Communication (JS)

You can communicate with the embedded editor through the JS postMessage feature. Quoting from the docs:

The window.postMessage method safely enables cross-origin communication. Normally, scripts on different pages are allowed to access each other if and only if the pages that executed them are at locations with the same protocol (usually both https), port number (443 being the default for https), and host (modulo document.domain being set by both pages to the same value). window.postMessage provides a controlled mechanism to circumvent this restriction in a way which is secure when properly used.

Sending messages to the editor

Here I am going to assume that you're using the simple HTML embed example above (otherwise, you'll have to replace window.frames[0] with your identifier for the iframe node).

We support 3 different types of messages.

  • A simple string message:
    window.frames[0].postMessage('save', '*');
  • A JS object literal containing a name property with additional options
    window.frames[0].postMessage({name: 'save', hq_render: true});
  • A JSON serialized object containing a name property with additional options (required for IE9 compatibility):
    window.frames[0].postMessage('{"name": "save", "hq_render": true}');

Listening to messages from the editor

Listening to messages is possible by binding a listener to the window object (e.g. the editor's parent window). Whenever a message is sent to the parent window, it will be captured and console.log()ged in this case.


$(window).on('message', function(jQueryEvent) {
    // jQuery uses the "originalEvent" property as namespace for the plain JS event
    var data =;
    if (data.length && typeof data === 'string' && data[0] == '{') {
    // only parse the JSON after we're sure it's valid.
    data = JSON.parse(data);
    // happy capturing of events!

Plain JS

window.addEventListener('message', function(event) {
    var data =;
    if (data.length && typeof data === 'string' && data[0] == '{') {
        data = JSON.parse(data);
    // happy capturing of events!

Client → Editor

In the following calls, you'll be calling postMessage with the following MESSAGE to execute a command, optionally, other keys can be passed into the object if there are any.


Send a message to the editor to reload authentication cookies, This is useful for when you set cookies seperate from loading the editor.

MESSAGE{name: "refresh_userinfo"}


Send a message to the editor requesting to save the room, if it s a newly created room or a room owned by a different user then the save as dialog will be shown.

MESSAGE{name: "save"}
render_hqnoA HQ render will be requested after saving the room.
hide_dialognoHide the save dialog (requires setting a name in room_attributes manually)
room_attributesno unless hide_dialog specifiedSet room attributes, options include name (string), public (bool) and category (one of Living room, Bathroom, Dining room, Kitchen, Bedroom, Kids room, Garden, Office, Other)


Send a message to save and render the current room, Identical to the Take a 3d photo functionality in the editor GUI.

NOTICE: DEPRECATED! DO NOT USE - Instead, use save with the render_hq parameter set to true

MESSAGE{name: "save_and_render"}


Logs the currently logged in user out and refreshes user information afterwards

MESSAGE{name: "logout"}
This message has no other options.

Editor → Client

In these calls you're listening for messages being sent to the parent window by the editor. these are the calls that are dispatched based on available actions, e.g. if you try to save a room without being logged in you'll recieve a login required message which will allow you to undertake some action.

login required

Signals the parent window that the user has to be logged in to perform a certain action. When the editor is set up this way, it will not display a login popup (allows you to handle that yourself). This is useful for when you would like to create a custom login screen that works through your own website. If you're doing that it'd be a good idea to check the refresh_userinfo.

MESSAGE{name: "login required"}


Signals the parent window that the room has been saved, the room_id attribute is returned in the id field of the message.

MESSAGE{name: "saved", id: 12345678}