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.

Priority

Priority will determine the order in which the roles will be degraded. A lower number represents a higher priority.

Publish Strategies

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

Strategy	Description
Can share audio	Whether the role is allowed to publish the audio track or not.
Can share video	Whether the role is allowed to publish the video track or not
Can share screen	Whether the role is allowed to do screen share or not
Video quality	Quality 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 quality	Quality 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 will be used to determine what all roles, this role can subscribe to.

Strategy	Description
Subscribe to	You can select all the roles of the template which this role will subscribe
Subscribe Degradation	When 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.

Permission	Description
Can change any participant's role	With this permission, user will be able to change the role of the other participant's who are present in the room
Can mute any participant	With this permission, user will be able to mute any participant's audio and/or video.
Can ask participant to unmute	With this permission, user will be able to ask any participant to unmute their audio and/or video.
Can remove participant from the room	With this permission, user will be able to remove any participant from the current session of the room.
Can end current session of the room	With this permission, user will be able to end the current session of the room.
Can receive room state	With this permission, user will be able to receive room state like peer-count and peer-list on the preview screen.

Advanced Settings

As the name suggests, Advanced Settings section contains more settings and controls for the advanced user.

Template

Room State

Room state settings control the strategy of sending room state updates sent to our client SDK consumers.

Setting	Description
Room-state Message Interval (in seconds)	Room-state data will be sent over a regular interval of these many seconds. Consequently, the room state displayed on the preview screen will refresh accordingly. This value must be a multiple of 5, between 5 and 3600 seconds, both inclusive.
Send Peer List in Room-state	Enabling this will send peer-list info of the room. If disabled, only the peer count is sent.
Enable Room-State	If enabled, room-state data will be sent to the preview screen. If disabled, no such room-state data will be sent.
Roles with room-state permission	This is the list of all the roles which will get the room-state data. You can also individually toggle these settings in the Roles tab under the Permissions section.

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

Name	Value	Required
Authorization	Bearer `{{management token}}`	Yes
Content-type	application/json	For `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": {} } }'

200: OK

 {
    "_id": "615e61b0ba65e77a89ba75c1",
    "name": "test-template",
    "customer": "60f7cc95f88117b9e47bf618",
    "default": true,
    "roles": {
        "admin": {
            "name": "admin",
            "publishParams": {
                "allowed": ["video", "screen", "audio"],
                "audio": {
                    "bitRate": 32,
                    "codec": "opus"
                },
                "video": {
                    "bitRate": 250,
                    "codec": "vp8",
                    "frameRate": 30,
                    "width": 480,
                    "height": 270
                },
                "screen": {
                    "codec": "vp8",
                    "frameRate": 10,
                    "width": 1920,
                    "height": 1080
                }
            },
            "subscribeParams": {
                "subscribeToRoles": ["guest"],
                "maxSubsBitRate": 3200,
                "subscribeDegradation": {}
            },
            "permissions": {}
        },
        "student": {
            "name": "student",
            "publishParams": {
                "allowed": ["video", "screen", "audio"],
                "audio": {
                    "bitRate": 32,
                    "codec": "opus"
                },
                "video": {
                    "bitRate": 250,
                    "codec": "vp8",
                    "frameRate": 30,
                    "width": 480,
                    "height": 270
                },
                "screen": {
                    "codec": "vp8",
                    "frameRate": 10,
                    "width": 1920,
                    "height": 1080
                }
            },
            "subscribeParams": {
                "subscribeToRoles": ["guest"],
                "maxSubsBitRate": 3200,
                "subscribeDegradation": {}
            },
            "permissions": {}
        },
        "teacher": {
            "name": "teacher",
            "publishParams": {
                "allowed": ["video", "screen", "audio"],
                "audio": {
                    "bitRate": 32,
                    "codec": "opus"
                },
                "video": {
                    "bitRate": 250,
                    "codec": "vp8",
                    "frameRate": 30,
                    "width": 480,
                    "height": 270
                },
                "screen": {
                    "codec": "vp8",
                    "frameRate": 10,
                    "width": 1920,
                    "height": 1080
                }
            },
            "subscribeParams": {
                "subscribeToRoles": ["guest"],
                "maxSubsBitRate": 3200,
                "subscribeDegradation": {}
            },
            "permissions": {}
        }
    }
}

Body Parameters

Name	Type	Description	Required
name	`string`	A 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	`boolean`	Whether 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	`object`	Map of `{roleName:roleObject}`. Some sane defaults are set for values that are not provided in the roles object.	No
settings	`object`	Global settings for this template.	No

roleObject

Name	Type	Description	Required
publishParams	`object`	Publish parameters for this role.	No
subscribeParams	`object`	Subscribe parameters for this role.	No
permissions	`object`	Permissions for this role.	No
priority	`int`	Priority of the role for subscription/publishing. Range: `1`-`10`	No

publishParams

Name	Type	Description	Required
allowed	`array`	Allowed tracks. Subarray of [`audio`, `video`, `screen`].	No
audio	`object`	Audio publish parameters.	No
video	`object`	Video publish parameters.	No
screen	`object`	Screenshare publish parameters.	No

audio

Name	Type	Description	Required
bitRate	`int`	Audio Max bitrate of audio track in kbps. Range: `16`-`128` Default: `32`	No
codec	`string`	Codec for the audio track. Options: [`opus`] Default: `opus`	No

video

Name	Type	Description	Required
bitRate	`int`	Max bitrate of video track in kbps. Range: `30`-`2000` Default: `256`	No
codec	`string`	Codec for the video track. Options: [`vp8`] Default: `vp8`	No
frameRate	`int`	Max number of video frames per second. Range: `1`-`30` Default: `25`	No
height	`int`	Height of the video track. Range: `50`-`1080` Default: `180`	No
width	`int`	Width of the video track. Range: `50`-`1920` Default: `320`	No

screen

Name	Type	Description	Required
bitRate	`int`	Max bitrate of screen track in kbps. Range: `>=500` Default: `1024`	No
codec	`string`	Codec for the screen track. Options: [`vp8`] Default: `vp8`	No
frameRate	`int`	Max number of screen frames per second Range: `1`-`30` Default: `10`	No
height	`int`	Height of the screen track. Range: `270`-`1080` Default: `720`	No
width	`int`	Width of the screen track. Range: `480`-`1920` Default: `1280`	No

subscribeParams

Name	Type	Description	Required
maxSubsBitRate	`int`	Maximum bitrate (in kbps) that can subscribed.	No
subscribeToRoles	`array`	List of roles which can be subscribed to.	No
subscribeDegradation	`object`	Subscribe degradation parameters (adding this enables screen simulcast).	No

subscribeDegradation

Name	Type	Description	Required
packetLossThreshold	`int`	Threshold for packet loss. Range: `1`-`100` Default: `50`	No
degradeGracePeriodSeconds	`int`	Degrade grace period (in seconds). Range: `1`-`10` Default: `1`	No
recoverGracePeriodSeconds	`int`	Recover grace period (in seconds). Range: `1`-`10` Default: `4`	No

permissions

Name	Type	Description	Required
endRoom	`boolean`	Permission to end room for all.	No
removeOthers	`boolean`	Permission to remove others from the room.	No
mute	`boolean`	Permission to request others to mute them.	No
unmute	`boolean`	Permission to request others to unmute them.	No
changeRole	`boolean`	Permission to request others to change their role.	No

settings

Name	Type	Description	Required
region	`string`	Region in which the room will be hosted by default. Possible values could be `in`, `us`, `eu` or `auto` (automatic region selection).	No
recording	`object`	Object of type `recording`. This object contains information for enabling recording/setting storage location for recordings.	No

recording

Name	Type	Description	Required
enabled	`boolean`	Enable the SFU recording for its rooms. Disabled by default.	No
upload	`object`	Object of type `upload`. This object contains information on recordings storage location. If you want to store recording with 100ms, and not use your own s3, don't add this to the object	No

upload

Name	Type	Description	Required
type	`string`	Upload Destination type. Currently, only s3 is supported.	Yes
location	`string`	Name of the AWS s3 bucket in which you want to store all recordings	Yes
prefix	`string`	Upload prefix path	Yes
options	`object`	Additional configurations of type Options to be used for uploading	No
credentials	`object`	Object of type `Credentials`. This is used to share AWS credentials to access the s3 bucket specified.	No

options

Name	Type	Description	Required
region	`string`	Region of the AWS account hosting the s3 bucket. If not provided it is assumed to be `ap-south-1`	No

Credentials

Name	Type	Description	Required
key	`string`	`access key ID` for the AWS account hosting the s3 bucket for storing recordings	Yes
secret	`string`	`secret access key` for the AWS account hosting the s3 bucket for storing recordings	Yes

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

200: OK

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

Name	Type	Description	Required
roleObject	`object`	Role object correspoding to the given role.	Yes
name	`string`	Providing 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" }'

200: OK

 {
    "region": "us"
}

Body Parameters

Name	Type	Description	Required
region	`string`	Region 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}}'

200: OK

 {
    "limit": 10,
    "data": [
        {
            "_id": "615dbca1ba65e77a89a8e2b8",
            "name": "test-template10",
            "customer": "60f7cc95f88117b9e47bf618",
            "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,
                        "subscribeDegradation": {}
                    },
                    "permissions": {},
                    "priority": 1
                }
            },
            "settings": {
                "region": "in"
            }
        }
    ],
    "last": "615dbca1ba65e77a89a8e2b8"
}

URL Parameters

Name	Type	Description	Required
name	`string`	Name of the template.	No
id	`string`	ID of the template.	No
start	`string`	Returned 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	`int`	Number of templates to return (max `20`).	No
default	`boolean`	Whether 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}}'

200: OK

 {
    "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,
        "subscribeDegradation": {}
    },
    "permissions": {},
    "priority": 1
}

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

200: OK

 {
    "region": "in"
}

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

200: OK

 {
    "_id": "615dbca1ba65e77a89a8e2b8",
    "name": "test-template10",
    "customer": "60f7cc95f88117b9e47bf618",
    "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,
                "subscribeDegradation": {}
            },
            "permissions": {},
            "priority": 1
        }
    },
    "settings": {
        "region": "eu"
    }
}

Body Parameters

Name	Type	Description	Required
name	`string`	If 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	`boolean`	Whether 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	`object`	Modified 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	`object`	Modified 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'

204: No Content

Basics Webhook

Edit this File

Templates and Roles

Introduction

Roles

Name

Priority

Publish Strategies

Subscribe Strategies

Permissions

Advanced Settings

Room State

API reference

Headers required for APIs

Create Template API

Body Parameters

roleObject

publishParams

audio

video

screen

subscribeParams

subscribeDegradation

permissions

settings

recording

upload

options

Credentials

Create/Modify Role API

Body Parameters

Update Settings API

Body Parameters

Get Templates API

URL Parameters

Get Role API

Get Settings API

Modify Template API

Body Parameters

Delete Role API