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

Leader Mode useruserclient_urlclient_url

See more about the client_url paramter 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 when a Space is created. Once set, the endpoint-url cannot be updated.

Setting up Webhooks

You can set up your own webhooks by specifying them in the body of your POST request to the Launch endpoint when first creating the Space. Any webhooks sent on any subsequent calls for the same Space (as identified by the id) will be ignored.

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 and are now set in stone for this Space

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:

{
  "request": {
    "method": "POST",
    "url": "https://api.thelessonspace.com/v2/spaces/launch/",
    "headers": [
      {
        "name": "Authorization",
        "value": "Organisation __API_KEY__"
      }
    ],
    "postData": {
      "mimeType": "application/json",
      "text": "{\"id\": \"biology101_2023\", \"user\": {\"id\": \"Teacher_1\", \"name\": \"Peter Parker\", \"leader\": true, \"custom_jwt_parameters\": { \"meta\": { \"displayName\": \"Spiderman\" }}}}"
    }
  },
  "response": {
    "status": 200,
    "httpVersion": "HTTP/2",
    "headers": [
      {
        "name": "content-type",
        "value": "application/json"
      }
    ],
    "content": {
      "text": "{\"client_url\": \"https://go.room.sh/...\", \"api_base\": \"https://ew2-aa.room.sh/v1/room/\", \"room_id\": \"uuid\", \"secret\": \"uuid\", \"session_id\": \"uuid\",\"user_id\": \"int\"}",
      "mimeType": "application/json"
    }
  }
}

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

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 assinged 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 Follow 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 intitiate Read-only Mode which will prevent other users from making changes to any content in the workspace.
Banning & manging 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.

Webhooks

See Adding Webhooks above for an example.

Retries & Ordering

If your server returns a status code outside the 200 - 299 range, or takes longer than 30 seconds (including connection and response time), the webhook delivery will be considered a failure and retries will begin.

The retry algorithm uses an exponential backoff, and will attempt to deliver a payload up to 5 times. In order to not count retry delay in statistics, you can use the x-webhook-time time header, described below.

Events are guaranteed to be delivered in-order on a per-space basis and per-URL basis with a single exception for the case of all retries failing. In that case, subsequent events will still be delivered.

Headers

Four custom headers are included with each delivery. These are:

x-webhook-id Uniquely identifies the webhook payload. Retries use the same value.
x-webhook-event The type of event being dispatched.
x-webhook-timestamp An ISO8601 timestamp specifying when the webhook event took place.
x-webhook-signature A cryptographic signature for security and authentication.

Security

The x-webhook-signature header allows you to both authenticate that the request originates with Lessonspace (as only you and Lessonspace know the secret key) and also that the payload has not been modified. The signature is calculated as an HMAC (using the sha256 algorithm) of the webhook payload as stringified JSON (generated with JSON.stringify() in Node.js), using the space secret as the signing key.

If the payload is stringified using a similar operation in another language, such as json.dumps in Python, note that the semantics of JSON.stringify mean that all unimportant whitespace is automatically removed from the final string. For Python, an equivalent operation would be json.dumps(x, separators=(',', ':')).

It is not sufficient to simply copy-paste the payload and quote it to create a string.

The space secret is exposed in the response when making a request to the Launch API.

Events

All the webhooks.user webhooks have the same payload schema which is given below.

{
  "session": {
    "id": "internal identifier of the session"
  },
  "room": {
    "id": "internal identifier of the space"
  },
  "socketId": "internal socket id of the user",
  "user": {
    "id": "identifier of the user",
    "guest": "boolean flag indicating whether or not the user joined while signed in",
    "readOnly": "boolean flag indicating whether or not the user was in read only mode",
    "allowInvite": "boolean flag indicating whether or not the user had access to the Invite Others button",
    "meta": ...,
    "page": null,
    "av": ...
  },
  "nbf": ...,
  "exp": ...,
  "canLead": "boolean flag indicating whether or not the user can lead",
  "traceId": ...
}

{
  "id": "internal identifier of the session",
  "room": {
    "id": "internal identifier of the space"
  }
}

`webhooks.session.idle`

Triggered when all the users in a space are considered idle.

Payload Schema

{
  "id": "internal identifier of the session",
  "room": {
    "id": "internal identifier of the space",
    "allUsersIdle": true,
    "becameIdleAt": "ISO860 date string indicating the datetime that the session became idle"
  }
}

`webhooks.session.end`

Triggered when a space registers it's last user leave, or timeouts have been reached.

Payload Schema

{
  "id":  "internal identifier of the session",
  "room": {
    "id": "internal identifier of the space",
    "allUsersIdle": "boolean indicating whether or not all users are idle",
    "becameIdleAt": "ISO860 date string indicating the datetime that the session became idle"
  },
  "summary": {
    "start": "ISO860 date string indicating start datetime of the session",
    "end": "ISO860 date string indicating end datetime of the session"
  },
  "reason": {
    "state": "ended",
    "extra": "empty"
  }
}

Spaces

Space Configurations

Space Identification

Body Schema

Adding a Leader

Body Schema

Adding Webhooks

Setting up Webhooks

Body Schema

Creating a Space

Body Schema

Joining a Space

Leader Mode

Webhooks

Retries & Ordering

Headers

Security

Events

`webhooks.user.join`

`webhooks.user.idle`

`webhooks.user.leave`

`webhooks.session.start`

Payload Schema

`webhooks.session.idle`

Payload Schema

`webhooks.session.end`

Payload Schema