Sessions

See for an explanation of "What is a Session?".

At Lessonspace a Session is created when a connection (user) first joins a Space. This means that if you request a client_url from the API, but never use it, no corresponding Session will appear in your Session list. The session_id given in the API response will remain the same on multiple invocations if no Session has actually started.

Billing for a Session only starts when there are 2 or more connections (users) present in a Space - including when a user joins the same Space from multiple tabs/browsers.

A single connection (user) can spend as much time in the Space as they like at no cost! We will only bill you when you are making money!

Following the use cases discussed in , we will be looking at creating sessions with a Space per Teacher/Student pair. This has a few advantages when creating Sessions with Students:

When Students have been assigned a client_url that will always open their private Space with all the initial settings assigned when the client_url was first generated. Settings for Students can be changed by calling the Launch endpoint with updated settings and/or features and reassigning the client_url to the same Student.
Spaces are persistent which allow a Student to easily jump on and see old notes from past lessons at any time. All they have do is open their private client_url!

Not all settings for a Space can be changed when requesting a new client_url. Refer to the Launch endpoint documentation for specifics.

Inviting Users

Inviting Users to Spaces assumes that the Spaces have already been created and are uniquely identified within your Organisation. See for more information.

When inviting users, you must add the user object to the payload sent when POSTing to the Launch endpoint. This process is similar to creating a Space, but the id key is populated with a Space we know exists and want to invite users to, in our scenario "biology101_2023".

If the Launch endpoint is called with only the id key populated, this will be what we call a guest link. This simply means that when Students join the Space via the client_url they will be assigned the name "Guest". They will also not be uniquely identifiabl in your Lessonspace analytics.

User Object

The user object is used for two reasons:

In order to personalize the Space when Students join; their unique client_urls contain all the required parameters to identify the user joining - for example display name.
To create a persistent User within your Lessonspace Organisation representing the Student/Teacher, this can be used for in-lesson analytics.

Below are the necessary options required to create unique client_urls for your Students.

The default setting for leader is false, hence, this can be omitted for a Student.

Body Schema

{
  "id": "biology101-2023",
  "user":
  {
    "id":"BioStudent_1",
    "name":"Bruce Wayne",
    "email":"bruce@wayne.co.za",
    "role": "student",
    "leader":false,
    "custom_jwt_parameters":
    {
      "meta":
      {
        "displayName": "Batman"
      }
    }
  }
}

The below focuses on describing the User object only. See for more details on the whole object.

id Your unique identifier for the User to be created. This can be used later to associate future links with the same User.
name The name assigned to the User which will be displayed in the Lessonspace dashboard.
email The email associated with the User. Emails are also unique for each user.
leader Enable or disable .
custom_jwt_parameters Parameters used to identify Users joining the Space, restrict user access to the Space (see ) and provide additional arbitrary information to identify the Space or User in webhooks.
meta.displayName Name that is displayed within the Space.

The user object is not designed as a security mechanism. Anyone who gains access to the client_url issued when creating the Invite will be able to attempt to join the space with the details encoded into the user object. Thus, the client_url must be kept private by the intended person if authentication is required and your system does not provide any (see Lessonspace Authentication).

Creating `client_url`s

Once you have defined your user object, the next step is creating the unique client_urls that can be used to access the Space assigned.

Subsequent calls to the Launch endpoint with the same Space id and user.id values will only change the following:

session_id This will only change if any previous Session created by prior calls has started and ended. If any previous Session was never used, the session_id will be unchanged.
If any changes to the POST body have been made or added, these changes will be set for the newly returned client_url. These changes are per-request which means that only the user who has access to the client_url will be affected.

{
  "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\":\"BioStudent_1\",\"name\":\"Bruce Wayne\",\"leader\":false, \"custom_jwt_parameters\": {\"meta\": {\"displayName\": \"Batman\"}}}}"
    }
  },
  "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"
    }
  }
}

By default the id field takes on the same value as name. You can specify a different id in the user object to distinguish between users with the same name, or for linking users to event data for analytics. To see more details about the User Object check out our Postman collection.

Session Restrictions

Calling the Launch endpoint can also be used to assign restrictions to Sessions when being created. These will apply to anyone who joins with that specific client_url.

These are not global restrictions on the Space, but rather link-specific. Different users may have different restrictions.

Generate a single-use link

To generate a link that will be valid only once, set the single_use key to true. After a user has joined the Space via the client_url, other users will be blocked from entering the Space using the same link.

The first user can still rejoin the session if they are disconnected or reload the page, as long as they rejoin before the session ends. This link cannot be shared with other users or reused later on.

The redeemed single-use token is currently stored in the browser's local storage. Local storage is typically disabled in private browsing modes like Incognito. This means that the single-use feature will not work as expected if the client is using private browsing or has local storage disabled (either manually or via addons).

Body Schema

{
  "id": "biology101-2023",
  "user":
  {
    "id":"BioStudent_2",
    "name":"Barry Allen",
    "role": "student",
    "email":"barry@fast.co.za",
    "leader":false,
    "single_use": true, // All we need to add
    "custom_jwt_parameters":
    {
      "meta":
      {
        "displayName": "The Flash"
      }
    }
  }
}

A session ends 30 seconds after the last user has left, or if all users in the space have been idle for 5 minutes.

Generate a link that is only valid for a given time

The timeframe for which a generated link can be used can be limited by specifying a timeouts parameter. This means it is possible to generate a link for one user, allowing them to join now, and a link for another user where they can only join at a later time.

The structure for the timeouts parameter is as follows:

"timeouts": {
  "not_before": "2019-12-12T06:00",
  "not_after": "2019-12-12T08:00"
}

not_before is an ISO8601 timestamp that specifies the earliest time that a link can be used to join a Space.

not_after is an ISO8601 timestamp that specifies the latest time that a link can be used to join a Space. It will stop new users from joining and also stop existing users from rejoining (including if they disconnect and automatically try to rejoin).

Using timeouts.not_after by itself will not kick any current users out of the Space when the timeout is reached. Users already in the Space will still be able to use some of the whiteboard tools. However, they will not be able to make API requests and therefore some functionality (such as uploading a new image or exporting the room) will not work.

Body Schema

{
  "id": "biology101-2023",
  "user":
  {
    "id": "BioStudent_2",
    "name": "Barry Allen",
    "role": "student",
    "email": "barry@fast.co.za",
    "leader": false,
    "single_use": true,
    "custom_jwt_parameters":
    {
      "meta":
      {
        "displayName": "The Flash"
      }
    }
  },
  "timeouts":
  {
    "not_before": "2023-12-12T06:00",
    "not_after": "2023-12-12T08:00"
  }
}

How to forcibly end a session at a particular time

Suppose you want to have a session that should last 30 minutes. If you want the session to automatically end at a predetermined time and kick all users, this can be achieved by using a combination of the timeouts.not_before and timeouts.not_after parameters mentioned above, and the user.custom_jwt_parameters parameter.

By setting the kickOnExp (meaning "kick on expiry") attribute of the custom_jwt_parameters to true, that user will be kicked out of the Space when the time specified in the not_after timestamp is reached.

A full example payload would look something like:

Body Schema

{
  "id": "biology101-2023",
  "user":
  {
    "id": "BioStudent_2",
    "name": "Barry Allen",
    "role": "student",
    "email": "barry@fast.co.za",
    "leader": false,
    "single_use": true,
    "custom_jwt_parameters":
    {
      "kickOnExp": true,
      "meta":
      {
        "displayName": "The Flash"
      }
    }
  },
  "timeouts":
  {
    "not_before": "2023-12-12T06:00",
    "not_after": "2023-12-12T08:00"
  }
}

Prompt users about the session ending

It is possible to create a "soft" limit on the end of a session and prompt leaders to act accordingly. The leader will have the option to extend the session by 10 minutes. At the end of these 10 minutes, the leader will be prompted again.

This is achieved by using the user.custom_jwt_parameters.softExp field and passing the desired time to send the prompt in Unix/POSIX time format.

"custom_jwt_parameters": {
  "softExp": 1660740441 // Wed, 17 Aug 2022 12:47:21 GMT (Time in UNIX epoch seconds)
}

Moreover, this can be used in combination with the timeouts parameter and user.custom_jwt_parameters.kickOnExp fields to create "hard" limits on the beginning and end of the session. The session will not be accessible before the time given in timeouts.not_before and users will be kicked once the time given in timeouts.not_after is reached. A full example payload would look something like this:

Body Schema

{
  "id": "biology101-2023",
  "user":
  {
    "id": "BioStudent_2",
    "name": "Barry Allen",
    "role": "student",
    "email": "barry@fast.co.za",
    "leader": false,
    "single_use": true,
    "custom_jwt_parameters":
    {
      "kickOnExp": true,
      "softExp": 1660740441, // Wed, 17 Aug 2022 12:47:21 GMT (Time in UNIX epoch seconds)
      "meta":
      {
        "displayName": "The Flash"
      }
    }
  },
  "timeouts":
  {
        "not_before": "2022-08-17T12:00:00+00:00",
        "not_after": "2022-08-17T13:00:00+00:00"
    }
}

Session End

Redirecting a user

Should you wish to, you can add URL parameters to the client_url to redirect a user to a specific URL when a session ends. This can be useful if you want to redirect a user back to your website after a session.

Upon clicking the Leave Session or if the leader clicks End Session for All, a pop up window will be displayed notifying the user that the session has ended and a button with the specified link and text will be shown.

This can be achieved by using the holodeck_parameters parameter when calling the Launch endpoint.

The parameter is a JSON object with 3 keys:

customCloseUrl is the URL you want the user to be redirected to.
customCloseName is the phrase to be displayed on the button.
customCloseAutomatic is a boolean that can be set to true so that the user will be redirected automatically after the end of the session (without needing to click the button).

customCloseAutomatic has to be passed as a string and not as a boolean data type.

Body Schema

{
  "id": "biology101-2023",
  "user":
  {
    "id": "BioStudent_2",
    "name": "Barry Allen",
    "role": "student",
    "email": "barry@fast.co.za",
    "leader": false,
    "custom_jwt_parameters":
    {
      "meta":
      {
        "displayName": "The Flash"
      }
    }
  },
  "holodeck_parameters":
  {
    "customCloseUrl": "http://mywebsite.com",
    "customCloseName": "Back to My Website",
    "customCloseAutomatic": "true"
  }
}