Lessonspace
Documentation
API Reference

Creating Spaces

See Spaces for an explanation of "what is a Space?"

Depending on your business operations, our integration offers two unique approaches to consider:

  • Creating a Space for each Teacher/Student pair. This is the preferred use case and will be our scenario going forward. Spaces are persistent and this gives each student their own private Space.
  • Creating a Space for each Teacher to use for multiple Students. While this is an easy to setup use case, it doesn't take full advantage of the persistent Spaces - each lesson will require the Space to be cleared manually, closing old tabs and creating new ones, etc.

There are no additional costs incurred for the number of Spaces you create, but depending on the age of the Spaces there may be charges incurred for storage of the Session Playbacks for those Spaces.

Space Configurations

There are a few requirements to consider before creating a Space, which are outlined below:

Space Identification

The Launch endpoint requires the id key to be populated. The id key uniquely identifies the Space and can be an identifier of your choosing, with a maximum length of 64 characters.

A response with a status code of 201 indicates that a new Space has been created. If a Space with the corresponding id already exists for your organisation, a status code of 200 will be returned and the details of the existing Space will be retrieved.

Body Schema

{
 "id":"biology101-2023"
}

Adding a Leader

You can include Leader Mode in the Space configuration by including the user object in the payload. The user object has mutiple settings with which you describe the rights and identity of the users who will be joining the Space via the returned client_url parameter. For now we will create a Leader as the returned client_url which, in our scenario, will be used by the Teacher.

See more about the client_url parameter below and the user object here.

A leader or a general user (student) can be added to a Space at any future date. It is, however, more convenient to perform this when the Space is first being created and thus reduces the number of calls to the Launch endpoint.

Body Schema

{
  "user":
  {
    "id":"Teacher_1",
    "name":"Peter Parker",
    "role": "teacher",
    "leader":true, // Enabling Leader Mode
    "custom_jwt_parameters":
    {
      "meta":
      {
        "displayName": "Spiderman"
      }
    }
  }
}

Adding Webhooks

The Lessonspace API provides the option to assign webhooks which can communicate real-time metrics such as user joins, session ends, etc. to your system.

The webhooks have to be set using the Launch endpoint.

Setting up Webhooks

You can set up your own webhooks by specifying them in the body of your POST request to the Launch endpoint. Any webhooks sent on any subsequent calls for the same Space (as identified by the id) will fully overwrite existing ones; they will not be merged in. This allows you to remove webhooks. You can leave webhooks as-is by simply not sending a new webhooks property.

Body Schema

{
  "webhooks": {
    "session": {
      "start": "<endpoint-url>",
      "end": "<endpoint-url>",
      "idle": "<endpoint-url>"
    },
    "user": {
      "join": "<endpoint-url>",
      "leave": "<endpoint-url>",
      "idle": "<endpoint-url>"
    }
  }
}

Creating a Space

Given the above, an example of the body for a POST to the Launch endpoint can be seen below. This will create a Space with the following configuration (following the configuration as mentioned above):

  • The Space will be identified as "biology101_2023"
  • The returned client_url will be for the Teacher "Peter Parker" who will have Leader Mode enabled (leader set to true)
  • The necessary webhooks have been assigned.

Other useful ids could be some sort of relationship identifier for the people intended to join the Space, e.g. teacher123_student456. You could also use a term (as in our case) that identifies the lesson or course at hand, e.g. biology101_2023.

Body Schema

{
  "id": "biology101_2023",
  "user":
  {
    "id":"Teacher_1",
    "name":"Peter Parker",
    "role": "teacher",
    "leader":true, // Enabling Leader Mode
    "custom_jwt_parameters":
    {
      "meta":
      {
        "displayName": "Spiderman"
      }
    }
  },
  "webhooks":
  {
    "session":
    {
      "start": "<endpoint-url>",
      "end": "<endpoint-url>",
      "idle": "<endpoint-url>"
    },
    "user":
    {
      "join": "<endpoint-url>",
      "leave": "<endpoint-url>",
      "idle": "<endpoint-url>"
    }
  }
}

It is possible to have multiple potential leaders in a Space but we do not recommend this. Having multiple users leading at the same time will often lead to undesirable behaviour.

Below is a demo example using cURL, copy and paste it to give it a try - webhooks omitted:

Joining a Space

Upon a successful Launch request, you will receive a JSON object similar to the following:

{
  "client_url" : "https://go.room.sh/...",
  "api_base" : "https://<region>.room.sh/v1/room/",
  "room_id" : "uuid",
  "secret" : "uuid",
  "session_id" : "uuid",
  "user_id" : "int"
}

Well done! Now open the client_url in your browser and you will be greeted by the lobby!

A little information about the returned object now follows (with a big focus on the client_url):

  • client_url refers to the raw URL of the Space itself (this url will contain go.room.sh). This URL has all of the settings specified by the user object (and other Additional Features) encoded as parameters. This allows you to create additional user specific client_urls for your Spaces depending on user requirements. See Inviting Users for more information.

It is important to understand that the returned client_url uses all your default organisation settings if they are not set the in body of the POST request. This means that the URLs will contain the settings (state) of your organisation on creation and not when they are being used. If you create a link and change the organisation settings later these will not be applied to the old client_url; you will need to call the Launch Endpoint with the same Space ID again in order to apply the updated settings.

  • api_base the endpoint used for all live sessions. This is region-specific and will automatically find the nearest server to you for low latency (unless explicitly overridden in the Launch parameters).
  • room_id this UUID is used to identify your space within our backend (which manages sessions and whiteboard). It is the same identifier used for the Space in the Lessonspace API.
  • secret token to ensure all calls to our backend are authenticated.
  • session_id refers to the ID of the upcoming session. This ID will only change once a session has started and subsequently ended. Subsequent calls will then generate a new session_id.
  • user_id is the unique identifier assigned to the user. This references the user record in Lessonspace database.

This client_url must be kept private and is only for use by the Tutor/Teacher assigned to the Space. See more about Leader Mode below.

Leader Mode

A user with leader mode enabled will be given certain privileges over and above all standard users (ie. those with leader mode set to false). These privileges include access to certain features and control over certain user actions.

Some examples include:

  • Inviting others to the Space from within the Space.
  • Ending Sessions and thus closing the space to all other users.
  • Ability to enable Leader Mode which will cause students views to always follow the leader.
  • Ability to control other users audio and video in the space (mute, request unmute, etc.)
  • Can turn off leading mode at any time to temporarily give back some control to the other users.
  • Can initiate Read-only Mode which will prevent other users from making changes to any content in the workspace.
  • Banning & managing banned users.

Leader mode is not designed as a security mechanism. By using the Javascript console, any peer could disable it and move around the Space freely.