Templates and Roles

Introduction

Template is the blueprint of the room. It defines the settings of the room along with the behavior of users who are part of it. Room will inherit the properties from a template that you have specified while creating it. If you have not specified any template then it will pick the default template. Each template will be identified by its id or name. E.g. default_videoconf_7e450ffc-8ef1-4572-ab28-b32474107b89

Users can see or modify the templates by visiting Templates on Dashboard or via API(see below). After updating a template or some part of its like permissions, you need to rejoin or restart the session for the template updates to take place.

Template

Roles

Role is a collection of permissions that allows you to perform certain set of operations while being part of the room. It has the following attributes:

Name

Every role has a name that should be unique inside a template. This name will be used while generating app tokens and referencing inside a template.

Publish Strategies

Publish strategies will be used to determine the tracks and their quality which can be published by this role.

StrategyDescription
Can share audioWhether the role is allowed to publish the audio track or not.
Can share videoWhether the role is allowed to publish the video track or not
Can share screenWhether the role is allowed to do screen share or not
Video qualityQuality of the video track which is going to be published by the role. Currently, 6 video qualities 1080p,720p, 480p, 360p, 240p and 120p are predefined and the user can select one out of these values. This option will be visible only if the Can share video is enabled.
Screenshare qualityQuality of the screen which is going to be shared by the role. Currently, 2 video qualities 720p and 1080p are predefined and the user can select one out of these values. This option will be visible only if the Can share screen is enabled.

Subscribe Strategies

Subscribe strategies will be used to determine what all roles, this role can subscribe to.

StrategyDescription
Subscribe toYou can select all the roles of the template which this role will subscribe
Subscribe DegradationWhen this flag is turned on, one or more remote video tracks will be muted automatically when the network condition worsens. Such tracks will be marked as degraded. When the network condition improves, the degraded tracks will automatically be unmuted.

Permissions

Permissions will contain a list of additional privileges that this role will have.

PermissionDescription
Can change any participant's roleWith this permission, user will be able to change the role of the other participant's who are present in the room
Can mute any participantWith this permission, user will be able to mute any participant's audio and/or video.
Can ask participant to unmuteWith this permission, user will be able to ask any participant to unmute their audio and/or video.
Can remove participant from the roomWith this permission, user will be able to remove any participant from the current session of the room.
Can end current session of the roomWith this permission, user will be able to end the current session of the room.

API reference

Apart from the dashboard, a programmatic way to interact with templates is via API. You will need a management token as a bearer token for your requests. After updating a template, you might need to rejoin or initiate a new session for the template updates to take place.

Headers required for APIs

NameValueRequired
Authorization
Bearer {{management token}}Yes
Content-type
application/jsonFor POST requests

Create Template API

POST/policy/v1/templates
https://prod-policy.100ms.live/policy/v1/templates

This endpoint is used to create a template. A recommended way is to provide a list of roles with empty objects to get default values for various options corresponding to those roles, then update those roles by modifying them by create/modify role API.

curl 'https://prod-policy.100ms.live/policy/v1/templates' -H 'Authorization: Bearer {{management_token}}' -X POST -H 'Content-Type: application/json' -d '{ "name": "test-template", "default": true, "roles":{ "student": {}, "teacher": {}, "admin": {} } }'

Body Parameters

NameTypeDescriptionRequired
name
stringA unique identifier you can assign to 100ms templates. Accepted characters are a-z, A-Z, 0-9, and . - : _. If not provided, this is generated automatically.

Notes:
(1) If create Template is called with an existing template name, then that template will be overwritten.
(2) Providing template name will be helpful if you want to modify/delete the template using name.
No
default
booleanWhether this is default template for a customer. Default template for a customer is used when no template is provided in create Room api.No
roles
objectMap of {roleName:roleObject}. Some sane defaults are set for values that are not provided in the roles object.No
settings
objectGlobal settings for this template.No

roleObject

NameTypeDescriptionRequired
publishParamsobjectPublish parameters for this role.No
subscribeParamsobjectSubscribe parameters for this role.No
permissionsobjectPermissions for this role.No
priorityintPriority of the role for subscription/publishing.
Range: 1-10
No

publishParams

NameTypeDescriptionRequired
allowedarrayAllowed tracks. Subarray of [audio, video, screen].No
audioobjectAudio publish parameters.No
videoobjectVideo publish parameters.No
screenobjectScreenshare publish parameters.No

audio

NameTypeDescriptionRequired
bitRateintAudio Max bitrate of audio track in kbps.
Range: 16-128
Default: 32
No
codecstringCodec for the audio track.
Options: [opus]
Default: opus
No

video

NameTypeDescriptionRequired
bitRateintMax bitrate of video track in kbps.
Range: 30-2000
Default: 256
No
codecstringCodec for the video track.
Options: [vp8]
Default: vp8
No
frameRateintMax number of video frames per second.
Range: 1-30
Default: 25
No
heightintHeight of the video track.
Range: 50-1080
Default: 180
No
widthintWidth of the video track.
Range: 50-1920
Default: 320
No

screen

NameTypeDescriptionRequired
bitRateintMax bitrate of screen track in kbps.
Range: >=500
Default: 1024
No
codecstringCodec for the screen track.
Options: [vp8]
Default: vp8
No
frameRateintMax number of screen frames per second
Range: 1-30
Default: 10
No
heightintHeight of the screen track.
Range: 270-1080
Default: 720
No
widthintWidth of the screen track.
Range: 480-1920
Default: 1280
No

subscribeParams

NameTypeDescriptionRequired
maxSubsBitRateintMaximum bitrate (in kbps) that can subscribed.No
subscribeToRolesarrayList of roles which can be subscribed to.No
subscribeDegradationobjectSubscribe degradation parameters (adding this enables screen simulcast).No

subscribeDegradation

NameTypeDescriptionRequired
packetLossThresholdintThreshold for packet loss.
Range: 1-100
Default: 50
No
degradeGracePeriodSecondsintDegrade grace period (in seconds).
Range: 1-10
Default: 1
No
recoverGracePeriodSecondsintRecover grace period (in seconds).
Range: 1-10
Default: 4
No

permissions

NameTypeDescriptionRequired
endRoombooleanPermission to end room for all.No
removeOthersbooleanPermission to remove others from the room.No
mutebooleanPermission to request others to mute them.No
unmutebooleanPermission to request others to unmute them.No
changeRolebooleanPermission to request others to change their role.No

settings

NameTypeDescriptionRequired
regionstringRegion in which the room will be hosted by default. Possible values could be in, us, eu or auto (automatic region selection).No

Create/Modify Role API

POST/policy/v1/templates/:id/roles/:name
https://prod-policy.100ms.live/policy/v1/templates/{{templateID}}/roles/{{roleName}}

This endpoint is used to create/modify a role.

curl 'https://prod-policy.100ms.live/policy/v1/templates/{{templateID}}/roles/{{roleName}}' -H 'Authorization: Bearer {{management_token}}' -X POST -H 'Content-Type: application/json' -d '{ "name": "listener3", "publishParams": { "allowed": [ "video", "screen", "audio" ], "audio": { "bitRate": 40, "codec": "opus" }, "video": { "bitRate": 400, "codec": "vp8", "frameRate": 30, "width": 480, "height": 360 }, "screen": { "codec": "vp8", "frameRate": 10, "width": 1920, "height": 1080 } }, "subscribeParams": { "subscribeToRoles": [ "speaker", "moderator", "new-role-9880" ], "maxSubsBitRate": 3200, "subscribeDegradation": {} }, "permissions": {}, "priority": 1 }'

Body Parameters

NameTypeDescriptionRequired
roleObject
objectRole object correspoding to the given role.Yes
name
stringProviding a name renames the role to the provided name. If role with same name already exists, it gives an overwrite error.No

Update Settings API

POST/policy/v1/templates/:id/settings
https://prod-policy.100ms.live/policy/v1/templates/{{templateID}}/setings

This endpoint is used to update settings.

curl 'https://prod-policy.100ms.live/policy/v1/templates/{{templateID}}/settings' -H 'Authorization: Bearer {{management_token}}' -X POST -H 'Content-Type: application/json' -d '{ "region": "us" }'

Body Parameters

NameTypeDescriptionRequired
region
stringRegion in which the room will be hosted by default - in, eu, us or auto.No

Get Templates API

GET/policy/v1/templates?id=ID
https://prod-policy.100ms.live/policy/v1/templates?id={{templateID}}

This endpoint is used to fetch a template. This API can be used to fetch a template. Instead of id, URL param name can be provided to fetch by name. Providing no URL params fetches all templates for the customer. You can provide start/limit params for pagination.

curl 'https://prod-policy.100ms.live/policy/v1/templates?id={{templateID}}' -H 'Authorization: Bearer {{management_token}}'

URL Parameters

NameTypeDescriptionRequired
name
stringName of the template.No
id
stringID of the template.No
start
stringReturned dataset is sorted by decreasing order of IDs. Provide the ID of the last result set to start in reverse order from there.No
limit
intNumber of templates to return (max 20).No
default
booleanWhether template is default or not.No

Get Role API

GET/policy/v1/templates/:id/roles/:name
https://prod-policy.100ms.live/policy/v1/templates/{{templateID}}/roles/{{roleName}}

This endpoint is used to fetch a role.

curl 'https://prod-policy.100ms.live/policy/v1/templates/{{templateID}}/roles/{{roleName}}' -H 'Authorization: Bearer {{management_token}}'

Get Settings API

GET/policy/v1/templates/:id/settings
https://prod-policy.100ms.live/policy/v1/templates/{{templateID}}/settings

This endpoint is used to fetch settings.

curl 'https://prod-policy.100ms.live/policy/v1/templates/{{templateID}}/settings' -H 'Authorization: Bearer {{management_token}}'

Modify Template API

POST/policy/v1/templates?id=ID
https://prod-policy.100ms.live/policy/v1/templates?id={{tempalateID}}

This endpoint is used to modify a Template. You can also use the URL parameter name instead of id to modify a template by name. Providing the same name as a previous template overrides that template. You need to provide all options for roles and settings which you want to apply.

curl 'https://prod-policy.100ms.live/policy/v1/templates?id={{templateID}}' -H 'Authorization: Bearer {{management_token}}' -X POST -H 'Content-Type: application/json' -d '{ "roles":{ "student":{ "name":"student", "publishParams":{ "allowed":[ "screen", "audio" ], "audio":{ "bitRate":42, "codec":"opus" }, "video":{ "bitRate":250, "codec":"vp8", "frameRate":30, "width":480, "height":270 }, "screen":{ "codec":"vp8", "frameRate":10, "width":1920, "height":1086 } }, "subscribeParams":{ "subscribeToRoles":[ "teacher", "student" ], "maxSubsBitRate":2000 }, "priority":1 } }, "settings":{ "region":"eu" } }'

Body Parameters

NameTypeDescriptionRequired
name
stringIf you don't provide the name, earlier provided name is used. Trying to modify a template's name to match another existing template's name produces overwrite error.No
default
booleanWhether this is default template for customer. The default template for a customer is used when no template is provided in create room API.No
roles
objectModified map of {roleName:roleObject}. Since this is a POST request, you need to provide the whole roles object to modify/persist/override it.Yes
settings
objectModified settings. Since this is a POST request, you need to provide the whole settings object to modify/persist/override it.Yes

Delete Role API

DELETE/policy/v1/templates/:id/roles/:name
https://prod-policy.100ms.live/policy/v1/templates/{{templateID}}/roles/{{roleName}}

This endpoint is used to delete a role. Subsequent requests for deleting role which does not exist gives 404.

curl 'https://prod-policy.100ms.live/policy/v1/templates/{{templateID}}/roles/{{roleName}}' -H 'Authorization: Bearer {{management_token}}' -X DELETE -H 'Content-Type: application/json'