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:


If you own a whitelabel account and want to make use of customisations such as a custom logo, custom brand colors in the editor, the following URL has to be used:


Parameter Required Value
token no A 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_url no A room url as seen in a room (check success tab)
lang no Default: 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" height="768"></iframe>


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

Parameter Required Value
redirect_url yes The 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.


{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. You can also use the forceNew parameter to force this behaviour for an existing room.


{name: "save"}

Key Required Value
render_hq no A HQ render will be requested after saving the room.
forceNew no Forces ‘save as…’ behaviour for an existing room.
hide_dialog no Hide the save dialog (requires setting a name in room_attributes manually)
room_attributes no unless hide_dialog specified Set 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


{name: "save_and_render"}


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


{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.

This feature has to be enabled by us for your (whitelabel) instance of Roomstyler, contact us with the request to turn the “Login required message” feature on!


{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.


{name: "saved", id: 12345678}


Signals the parent window that there is some error. The message attribute will contain some text describing the error. Currently, the only possible error message is room is empty which occurs when user tries to save an empty room.


{name: "error", message: "room is empty"}