Meeting Room
Meeting rooms are the core component for organizing video calls in the Eyeson platform. They serve as virtual spaces where participants can join and collaborate through video communication.
Throughout this documentation, the terms "meeting room," "meeting," and "room" are used interchangeably with the same meaning. It's important to note that a single room can host multiple consecutive meetings over time.
Room Creation and Access
- Rooms are created using an API-Key request
- Each room has a unique identifier to control access
- Users receive a unique access key specific to both the meeting and user
- The access key grants entry to the meeting
Room Status
The API response provides room status information through ready states:
- User ready state
- Room ready state
- Global ready state (combines user and room states)
Start Meeting
If someone already created and joined the meeting, the user provided will join this existing meeting.
POST /rooms
HEADERS Authorization
RESPONSES 201 CREATED, 400 BAD REQUEST, 403 FORBIDDEN
REQUIRED user[name]
RECOMMENDED options[sfu_mode]=disabled, options[widescreen]=true, user[id]
Example Req/Res: Start Meeting
curl -X POST -H "Authorization: $API_KEY" -H "Content-Type: application/json" -d "{"user": {"name": "John Doe", "id": "johndoe"}, "options": {"sfu_mode": "disabled", "widescreen": true}" "https://api.eyeson.team/rooms"
Response Status: 201
{
"access_key": "VgoCcMUSQQ6h4zwpEfBuo0rZ",
"ready": false,
"locked": false,
"room": {
"id": "67d2febd7a286f59a7643884",
"name": "API magic",
"ready": false,
"started_at": "2025-03-13T15:50:21.347Z",
"shutdown": false,
"guest_token": "77Ua2Abc8ftGDNVzsixwvbcZ"
},
"team": {
"name": "API magic"
},
"user": {
"id": "johndoe",
"room_id": "67d2febd7a286f59a7643884",
"name": "John Doe",
"avatar": null,
"guest": false,
"blocked": false,
"ready": false
},
"links": {
"self": "https://api.eyeson.team/rooms/VgoCcMUSQQ6h4zwpEfBuo0rZ",
"gui": "https://app.eyeson.team/?VgoCcMUSQQ6h4zwpEfBuo0rZ",
"guest_join": "https://app.eyeson.team/?guest=77Ua2Abc8ftGDNVzsixwvbcZ",
"websocket": "https://api.eyeson.team/rt?access_key=VgoCcMUSQQ6h4zwpEfBuo0rZ"
},
"options": {
"show_names": true,
"show_label": true,
"exit_url": null,
"recording_available": true,
"broadcast_available": true,
"layout_available": true,
"layout": "auto",
"reaction_available": true,
"suggest_guest_names": true,
"lock_available": false,
"kick_available": true,
"sfu_mode": "disabled",
"layout_users": null,
"layout_name": null,
"layout_map": null,
"voice_activation": false,
"custom_fields": {},
"widescreen": true,
"background_color": "#121212"
},
"playbacks": [],
"presentation": null,
"broadcasts": [],
"recording": null,
"snapshots": [],
"waiting_list": [],
"signaling": {
"type": "sepp",
"options": {
"client_id": "67d2febd7a286f59a7643886",
"conf_id": "67d2febd7a286f59a7643885",
"auth_token": "eyJhbGciOiJFUzM4NCJ9.eyJpc3MiOiJleWVzb24tY29tYXBpIiwiY2xpZW50X2lkIjoiNjdkMmZlYmQ3YTI4NmY1OWE3NjQzODg2IiwiZXhwIjoxNzQxODg0NjIxLCJjb25mX2lkIjoiNjdkMmZlYmQ3YTI4NmY1OWE3NjQzODg1IiwiYXVkIjoiZXllc29uLXNlcHAifQ.fgRULd2AY85yNvFp3SDqo60ZLoYGn59gmOD3zw7ghzlMduq3C6SddgUq501TwulDWBt1Mubw53veH6tdF37b6snzpQGufQcmBrR2m6HNrGrTijL44NyRjcrbc7TjRKZo",
"endpoint": "wss://sig.eyeson.com/call",
"stun_servers": [
"stun:nuts.eyeson.com:3478"
],
"turn_servers": [
{
"urls": [
"turn:nuts.eyeson.com:3478",
"turn:nuts.eyeson.com:3478?transport=tcp",
"turns:nuts.eyeson.com:443?transport=tcp"
],
"username": "1741967421:67d2febd7a286f59a7643886",
"password": "jTF47lTP9hqOIWLRfeik2SSZjnY="
}
]
}
}
}
The links[gui]
is the host link and should be kept a secret as it can be used to start the meeting.
id
Type: STRING
(optional)
Default: RANDOM
Arbitrary and unique room id to get users into a specific meeting room. If empty, a random id will be returned.
name
Type: STRING
(optional)
Default: NULL
The readable name of a meeting room.
user[id]
Type: STRING
(optional)
Default: RANDOM
Custom, unique user ID to identify the user in further REST requests without the need to remember or save the Eyeson user ID, e.g., an internal user ID, an e-mail address, phone number, etc. If empty, a random id will be assigned.
user[name]
Type: STRING
(required)
Default:NULL
Display name of the user. This value gets used as the display value in the names overlay.
user[avatar]
Type: URL
(optional)
Default: NULL
Link to the public avatar image. Avatars will be displayed in the sidebar of our prebuilt user interface.
options[show_names]
Type: BOOLEAN
(optional)
Default: TRUE
Show display names in video. This uses the values from user[name]
options[show_label]
Type: BOOLEAN
(optional)
Default: TRUE
Show Eyeson logo in Prebuilt-UI. This option can be customized with your own logo
options[exit_url]
Type: URL
(optional)
Default: NULL
Prebuilt UI only: After the meeting is exited, the URL given will be displayed.
options[recording_available]
Type: BOOLEAN
(optional)
Default: TRUE
Allow recordings.
If set to FALSE
, related API requests will respond with status 405 METHOD NOT ALLOWED
.
options[broadcast_available]
Type: BOOLEAN
(optional)
Default: TRUE
Allow broadcasting.
If set to FALSE
, related API requests will respond with status 405 METHOD NOT ALLOWED
.
options[reaction_available]
Type: BOOLEAN
(optional)
Default: TRUE
Show gif media inserts in Prebuilt-UI.
If set to FALSE
, related API requests will respond with status 405 METHOD NOT ALLOWED
.
options[layout_available]
Type: BOOLEAN
(optional)
Default: TRUE
Allow layout updates.
If set to FALSE
, related API requests will respond with status 405 METHOD NOT ALLOWED
.
options[guest_token_available]
Type: BOOLEAN
(optional)
Default: TRUE
Provides guest token. In case you set this option to FALSE
you can give access to the room using the standard user request.
If set to FALSE
, related API requests will respond with status 405 METHOD NOT ALLOWED
.
options[lock_available]
Type: BOOLEAN
(optional)
Default: FALSE
Enable meeting lock. To lock the meeting follow the instruction in Lock Meeting
If set to FALSE
, related API requests will respond with status 405 METHOD NOT ALLOWED
.
options[kick_available]
Type: BOOLEAN
(optional)
Default: TRUE
Allow participant kick. To remove a user from the meeting follow the instruction in Kick User
If set to FALSE
, related API requests will respond with status 405 METHOD NOT ALLOWED
.
options[sfu_mode]
Type: STRING
(optional)
Default: ptp
Enables efficient routing of audio and video streams between 2 participants.
Value | Description |
---|---|
disabled | The meeting runs in MCU+ mode |
screencast | Limits the meeting layout to a screencast configuration |
ptp | For meetings with 2 participants |
In order to make use of all advanced features of Eyeson API you must disable the SFU
(Selective Forwarding Unit) mode.
Eyeson API is based on MCU+
(Multipoint Control Unit), which extends basic MCU
functions with advanced source and data
handling. For more information visit the product website.
options[widescreen]
Type: BOOLEAN
(optional)
Default: FALSE
If TRUE
the meeting runs in widescreen mode (16:9 aspect ratio), for FALSE
the meeting is in standard (4:3 aspect ratio).
options[background_color]
Type: STRING
(optional)
Default: #121212
Set meeting background color as hex RGB. Read more
options[audio_insert]
Type: STRING
(optional)
Default: audio_only
Displays the audio activity of participants.
Value | Description |
---|---|
enabled | Shows audio activity inserts of all participants |
disabled | Completely disables audio activity inserts |
audio_only | Only shows audio activity inserts for participants who are not in the video stream. |
options[audio_insert_position][x]
Type: NUMBER
(optional)
Default: NULL
X position value of the audio insert.
options[audio_insert_position][y]
Type: NUMBER
(optional)
Default: NULL
Y position value of the audio insert.
options[custom_fields][locale]
Type: LOCALE
(optional)
Default: en
Sets the preferred language for the Prebuilt-UI interface. English and German translations are officially maintained, while other language translations are community-contributed. For details on available translations and contribution guidelines, see the Web GUI Locale repository on GitHub
Valid values: en
, de
, fr
options[custom_fields][logo]
Type: URL
(optional)
Default: NULL
URL to the public file for a custom logo in Prebuilt-UI. If the URL is not set the Eyeson logo gets shown.
The logo only gets shown when options[show_label] is TRUE
.
options[custom_fields][hide_chat]
Type: BOOLEAN
(optional)
Default: FALSE
Hide chat in Prebuilt-UI.
options[custom_fields][virtual_background]
Type: BOOLEAN
(optional)
Default: FALSE
Enable Virtual Background selection in Prebuilt-UI.
options[custom_fields][virtual_background_allow_guest]
Type: BOOLEAN
(optional)
Default: FALSE
Enable Virtual Background selection for Guest users in Prebuilt-UI.
Use these virtual background control fields to disable background effects when participants need to demonstrate physical objects on camera. This helps prevent common issues where virtual backgrounds interfere with showing physical items like documents.
options[custom_fields][virtual_background_image]
Type: URL
(optional)
Default: NULL
Provide a custom Virtual Background image URL for selection in Prebuilt-UI.
Virtual backgrounds support custom static images. For optimal results, use images with a 4:3 aspect ratio. The selected image will automatically scale to cover the entire background area.
Be aware of CORS requirements. The image is loaded in the browser and processed as a virtual background. For the browser to allow access to the image, the URL must deliver it with valid CORS headers, specifically either Access-Control-Allow-Origin: https://app.eyeson.team
or Access-Control-Allow-Origin: *
.
Parameter Behavior
Parameters That Only Apply at Meeting Room Startup
When creating or joining a meeting, certain parameters can only be effectively set during room initialization and cannot be modified for a running instance:
room[id]
- Cannot be changed for a running room (changing it creates/joins a different meeting)room[name]
- Only applies at meeting room creation, changes are silently ignored for existing instancesoptions[widescreen]
- Only effective at meeting startup, subsequent changes are silently ignored
Required vs. Optional Parameters
user[name]
is the only required parameter (needed for UI elements, chat labels, voice recognition)- All other parameters are optional with server-generated defaults when omitted
Entity ID Mapping
- Specifying your own IDs (
user[id]
,room[id]
) allows for easier mapping to your internal systems - These are convenience features that simplify integration but aren't mandatory
Parameter Behavior by Category
User Object Parameters:
- All parameters inside the
user
object relate to specific participants - The
user
object can include acustom_fields
object - User parameters can be set for each joining user
Room Instance Parameters:
- Parameters outside the user object apply to the entire room instance
- Room options can technically be modified in subsequent join requests, but:
- Some options only take effect at room creation
- Changing options like
widescreen
after room startup
Get details of current meeting
GET /rooms/`ACCESS_KEY`
RESPONSES 200 OK, 404 NOT FOUND, 410 GONE
REQUIRED user in running meeting
Example Req/Res: Details of current Meeting
curl "https://api.eyeson.team/rooms/$ACCESS_KEY"
{
"access_key": "VgoCcMUSQQ6h4zwpEfBuo0rZ",
"ready": true,
"locked": false,
"room": {
"id": "67d2febd7a286f59a7643884",
"name": "API magic",
"ready": true,
"started_at": "2025-03-13T15:50:21.347Z",
"shutdown": false,
"guest_token": "77Ua2Abc8ftGDNVzsixwvbcZ"
},
"team": {
"name": "API magic"
},
"user": {
"id": "johndoe",
"room_id": "67d2febd7a286f59a7643884",
"name": "John Doe",
"avatar": null,
"guest": false,
"blocked": false,
"ready": true
},
"links": {
"self": "https://api.eyeson.team/rooms/VgoCcMUSQQ6h4zwpEfBuo0rZ",
"gui": "https://app.eyeson.team/?VgoCcMUSQQ6h4zwpEfBuo0rZ",
"guest_join": "https://app.eyeson.team/?guest=77Ua2Abc8ftGDNVzsixwvbcZ",
"websocket": "https://api.eyeson.team/rt?access_key=VgoCcMUSQQ6h4zwpEfBuo0rZ"
},
"options": {
"show_names": true,
"show_label": true,
"exit_url": null,
"recording_available": true,
"broadcast_available": true,
"layout_available": true,
"layout": "auto",
"reaction_available": true,
"suggest_guest_names": true,
"lock_available": false,
"kick_available": true,
"sfu_mode": "disabled",
"layout_users": null,
"layout_name": null,
"layout_map": null,
"voice_activation": false,
"custom_fields": {},
"widescreen": true,
"background_color": "#121212"
},
"playbacks": [],
"presentation": null,
"broadcasts": [],
"recording": null,
"snapshots": [],
"waiting_list": [],
"signaling": {
"type": "sepp",
"options": {
"client_id": "67d2febd7a286f59a7643886",
"conf_id": "67d2febd7a286f59a7643885",
"auth_token": "eyJhbGciOiJFUzM4NCJ9.eyJpc3MiOiJleWVzb24tY29tYXBpIiwiY2xpZW50X2lkIjoiNjdkMmZlYmQ3YTI4NmY1OWE3NjQzODg2IiwiZXhwIjoxNzQxODg0NjQzLCJjb25mX2lkIjoiNjdkMmZlYmQ3YTI4NmY1OWE3NjQzODg1IiwiYXVkIjoiZXllc29uLXNlcHAifQ.FJ65OTcF3bUgw0taUdCkklz0drf053IHjQwmu72p45iFgstzAnnMNQQ5KbQuWwg3PtTkw8L0LaXnO3f2V77FrhEnuHRSCEQpedg2rj1pvW9Vra6mchvZC5aFHIy-8Jfu",
"endpoint": "wss://sig.eyeson.com/call",
"stun_servers": [
"stun:nuts.eyeson.com:3478"
],
"turn_servers": [
{
"urls": [
"turn:nuts.eyeson.com:3478",
"turn:nuts.eyeson.com:3478?transport=tcp",
"turns:nuts.eyeson.com:443?transport=tcp"
],
"username": "1741967443:67d2febd7a286f59a7643886",
"password": "R3EckhA8JEKeDlg5hmKPNPY2a38="
}
]
}
}
}
End Meeting
DELETE /rooms/`ACCESS_KEY`
RESPONSES 204 NO CONTENT, 404 NOT FOUND, 410 GONE
This is something the user can do with the ACCESS_KEY
. If you build a custom UI, you would use this method to end a meeting.
Example Req/Res: End Meeting
curl -X DELETE "https://api.eyeson.team/rooms/$ACCESS_KEY"
No Response
Force Stop Meeting
DELETE /rooms/`ROOM_ID`
HEADERS Authorization
RESPONSES 204 NO CONTENT, 400 BAD REQUEST, 403 FORBIDDEN, 404 NOT FOUND
If you have the API_KEY
you can force stop a running meeting.
Example Req/Res: Force Stop Meeting
curl -X DELETE -H "Authorization: $API_KEY" "https://api.eyeson.team/rooms/$ROOM_ID"
Response Status: 204
Get list of current running meetings
GET /rooms
HEADERS Authorization
RESPONSES 200 OK, 403 UNAUTHORIZED
Example Req/Res: Get list of current running meetings
curl -H "Authorization: $API_KEY" "https://api.eyeson.team/rooms"
[
{
"id": "67d44a8a7a286f59a76438d7",
"name": "API magic",
"ready": true,
"started_at": "2025-03-14T15:26:02.538Z",
"shutdown": false,
"guest_token": "UCUKBgO7sWLOlV8AERC1BZUG"
}
]
page
Type: Integer
(optional)
Default: NULL
Fetch next set of rooms (limit is 25).
This parameter uses 0-based indexing, meaning the first page is 0, second page is 1, etc.
Lock Meeting
Meeting rooms can be locked to prevent new participants from joining. When a room is locked:
- Only current participants remain in the meeting
- No additional users can join
- The lock cannot be reversed during the meeting session
Users with an ACCESS_KEY
have privileged access and can exit and rejoin the locked room. Users with a GUEST_TOKEN
can only exit the room and cannot rejoin once it is locked. Before locking a room, ensure that all desired participants are present, as only the current participants will retain access.
There is no unlock. Once locked, there's no way to let new users join the running meeting.
POST /rooms/`ACCESS_KEY`/lock
RESPONSES 201 CREATED, 403 FORBIDDEN, 404 NOT FOUND, 410 GONE
If options[lock_available] is set to FALSE
, related API requests will respond with status 403 FORBIDDEN
.
Example Req/Res: Lock Meeting
curl -X POST -H "Content-Type: application/json" "https://api.eyeson.team/rooms/$ACCESS_KEY/lock"
Response Status: 201