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.

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.

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

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.

Webhooks are set using the Launch endpoint. For full details on webhook configuration, events, and payloads, see Webhooks.

Body Schema

{
  "webhooks": {
    "session": {
      "start": "<endpoint-url>",
      "end": "<endpoint-url>"
    },
    "user": {
      "join": "<endpoint-url>",
      "leave": "<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.

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>"
    }
  }
}

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 YOUR_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": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", // uuid
  "secret":  "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", // uuid
  "session_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", // uuid
  "user_id": 1 // integer
}

Now if you put the client_url in your browser, you will open your Space!

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 encoded as parameters, along with any feature configuration you've specified. This allows you to create additional user-specific client_urls for your Spaces depending on user requirements.

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

Leader Mode

A user with leader mode enabled will be given certain privileges over standard users, including the ability to invite others, end sessions, control participant audio/video, and initiate read-only mode.

For full details on Leader Mode capabilities and usage, see Leading Mode.