SpatialChat allows you to add websites to a room using the iFrame element.

The website that is loaded in the iframe can communicate with SpatialChat through the SpatialChat iframe API. This API allows the website to receive information about the current space and room or about the user.

Further in this document we will use terms: host - for a SpatialChat room. iframe - for a site embedded in SpatialChat room iframe.

Communication technology

window.postMessage() api (https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) is used as a communication channel.

Both host and iframe can listen and post messages. Iframe can post messages to window.parent or window.opener

API Surface

Messages are exchanged in a form of JSON object (no need to serialize manually) of a following format:

{
	name: string, // restricted to a list of supported message names,
  requestId?: string // optional id to match request message with response
	data: any // any payload corresponding to the message name
}

Workflow

1. Host subscribes to iframe messages as soon as iframe is added.
2. Iframe sends any available message.
3. Host responds to incoming messages by sending appropriate message back.

Available API Methods

Request: get_space_ids

data: undefined

Send this message wherever you want to know which space and room iframe is embedded into. Do not call this multiple times unless necessary, cache the result, it never changes within a session.

Response: space_ids

data: { spaceId: string, roomId: string, spaceSlug: string }

This is a response message to get_space_ids

Request: get_user_info

data: undefined

Send this message wherever you want to know the current space user info. User can change this data within a session.

Response: user_info

data: { id?: string, name?: string, about?: string, pronoun?: string, avatarUrl?: string }

This is a response message to get_user_info

API usage example

Request: get_user_info

postMessage(
 {
  name: 'get_user_info',
  requestId: 'qwe123' // optional
 },
 '<https://app.spatial.chat>'
)

Response: user_info

{
 name: 'user_info',
 requestId: 'qwe123' // in case the requestId was received in the request.
 data: {
   id?: string
   name?: string
   about?: string
   pronoun?: string
   avatarUrl?: string
 }
}

Security considerations

1. Make sure the target window is window.parent or window.opener.
2. Always set postMessage’s 2nd parameter targetOrigin. Iframe should set 'https://app.spatial.chat'.
3. Do not use postMessage’s 3rd parameter transfer.