About

This guide explains how to create and embed a Kaltura Room using a pre-configured Kaltura Application Framework (KAF) instance. It is intended for developers who want to create rooms programmatically and launch them in custom environments.

Before you start

To use Kaltura Rooms, you’ll need a Kaltura environment configured for rooms (powered by the Kaltura Application Framework). Please contact your Kaltura representative to do it for you.

Create a room

Follow these steps to create a new meeting room that can be embedded later.

Step 1: Generate an admin Kaltura Session (KS)

Call the session.start API with the following parameters:

Parameter	Description
partnerId	your Kaltura partner ID
secret	admin secret (from KMC > Settings > Integration Settings > Admin secret)
type	set to '2' for admin
userId	ID of the user who will be assigned as the room owner
expiry	duration (in seconds) that the KS will remain valid

Step 2: Send the room creation request

Send a POST request to the room creation endpoint of your KAF instance:

https://{KAF_INSTANCE_HOSTNAME}/embeddedrooms/index/create-room

Include the following JSON-encoded parameters in the POST body:

• ks (mandatory) - the admin KS that you created in the previous step.
• name (mandatory) - the name of the new room
• description (optional) - room description
• tags (optional) - comma-separated string of room tags
• templateRoomEntryId (optional) - ID of a pre-defined template that controls room appearance. Please contact your Kaltura representative to get the list of generally available room templates or to create a customized template for your organization. The default template is configured on the KAF instance level by the Kaltura representative
• roomModeratorUserIds (optional) - array of user IDs that will become room’s moderators
• chatModeratorUserIds (optional) - array of user IDs that will become chat moderators in the context of the room

Response

Successful response:

{
  "success": true,
  "data": {
    "id": "the ID of the new room entry"
  }
}

Error response:

{
  "success": false,
  "errorCode": "machineReadableErrorCode",
  "error": "Human-readable error description"
}

Example:

{
  "success": false,
  "errorCode": "invalidRequest",
  "error": "Mandatory parameter \"name\" is missing"
}

Possible error codes:

• invalidConfiguration: The KAF instance is not configured properly to use embedded meeting rooms. Please contact your Kaltura representative to fix this error.
• invalidRequest: The request was submitted with invalid or missing parameters. Please review the documentation and fix the request parameters to fix this error.
• internalError: A general error occurred while processing the request. Please contact the support team to fix this error, and pass the details of the request.

Embedding (viewing) a room

Open this URL in the browser to view the room: 

https://{KAF_INSTANCE_HOSTNAME}/embeddedrooms/index/view-room

Provide the following parameters when authenticating the request according to the KAF instance’s configurations:

Parameter	Description
entryId (mandatory)	the room ID (the one that you got in response from the room creation API)
roomModerator (optional)	Set to '1' to make the current user a room moderator during the session (even if the user was not added as a room moderator while creating the room), '0' or skip the parameter not to do so
chatModerator (optional)	Set to '1' to make the current user a chat moderator in the current user session (even if the user was not added as a chat moderator while creating the room), '0' or skip the parameter not to do so

For LTI authentication, use the standard LTI protocol to add the parameters above. For KS authentication, add the parameters above as privileges on KS.