Skip to main content

User

Joining a Room with a user​

There are two ways to join a room:

  • Found in the links section of the API response
  • No additional API communication needed
  • Works with any WebRTC-capable browser
  • Bound to specific user (DON'T share)

Guest URL (Prebuilt-UI)​

  • Uses a guest token
  • Format: https://app.eyeson.team/?guest=GUEST_TOKEN
  • Provides immediate access to the meeting room
  • Can be shared to allow guests to join a running meeting
info

All these features require a WebRTC-capable user agent, typically a modern web browser.

Fetch User Details​

GET /rooms/`ACCESS_KEY`/users/`CLIENT_ID`
RESPONSES 200 OK, 404 NOT FOUND, 410 GONE
Example Req/Res: Fetch User Details
Request
curl "https://api.eyeson.team/rooms/$ACCESS_KEY/users/$CLIENT_ID"
Response
{'avatar': None,
 'guest': False,
 'id': 'janedoe',
 'joined_at': '2025-03-17T09:07:50.743Z',
 'name': 'Jane Doe'}

How to Get a List of All Users in an Eyeson Meeting​

The most efficient way to maintain a real-time list of all participants is by using the Meeting Observer functionality:

  1. Setup the WebSocket connection:

    • Connect to https://api.eyeson.team/rt?room_id=YOUR_ROOM_ID
    • Include your API key for authentication (via header, WebSocket based on ActionCable, AnyCable protocol, or query parameter)
    • Subscribe to the RoomChannel

  2. Get initial user list:

    • When you first connect, you'll receive a room_update event
    • This event contains a participants array with all current users

  3. Track user changes:

    • Listen for participant_update events
    • Add users to your list when online: true
    • Remove users from your list when online: false

Register User​

To register another user, you will need an active meeting room. Follow the instructions and parameters to start a meeting. Since the room is already started a new user will be generated.

POST /rooms
HEADERS Authorization
RESPONSES 201 CREATED, 400 BAD REQUEST, 403 FORBIDDEN
REQUIRED id, user[name]
RECOMMENDED user[id]
Example Req/Res: Register User
Request
curl -X POST -H "Authorization: $API_KEY" -H "Content-Type: application/json" -d "{"id": "janesroom", "user": {"name": "Jane Doe", "id": "janedoe"}}" "https://api.eyeson.team/rooms"
Response
{
  "access_key": "9G1y4JiTV7mPV10ZlZ3YxQwN",
  "ready": false,
  "locked": false,
  "room": {
    "id": "janesroom",
    "name": "API magic",
    "ready": true,
    "started_at": "2025-03-17T09:02:22.800Z",
    "shutdown": false,
    "guest_token": "6R2KFOrUOL3MhE9LToUVUuau"
  },
  "team": {
    "name": "API magic"
  },
  "user": {
    "id": "janedoe",
    "room_id": "janesroom",
    "name": "Jane Doe",
    "avatar": null,
    "guest": false,
    "blocked": false,
    "ready": false
  },
  "links": {
    "self": "https://api.eyeson.team/rooms/9G1y4JiTV7mPV10ZlZ3YxQwN",
    "gui": "https://app.eyeson.team/?9G1y4JiTV7mPV10ZlZ3YxQwN",
    "guest_join": "https://app.eyeson.team/?guest=6R2KFOrUOL3MhE9LToUVUuau",
    "websocket": "https://api.eyeson.team/rt?access_key=9G1y4JiTV7mPV10ZlZ3YxQwN"
  },
  "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": true,
    "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": "67d7e66685dc14f5cccf7ef8",
      "conf_id": "67d7e51e7a286f59a764392f",
      "auth_token": "eyJhbGciOiJFUzM4NCJ9.eyJpc3MiOiJleWVzb24tY29tYXBpIiwiY2xpZW50X2lkIjoiNjdkN2U2NjY4NWRjMTRmNWNjY2Y3ZWY4IiwiZXhwIjoxNzQyMjA2MDcwLCJjb25mX2lkIjoiNjdkN2U1MWU3YTI4NmY1OWE3NjQzOTJmIiwiYXVkIjoiZXllc29uLXNlcHAifQ.sMFOM4zSnnTICrspbL05NJ3AG7uAceWnA8Z7F-PIXd44moSJRic-6Z86EaWjCo9LPeeF2s9UPrY107MKAK9_yrz-M4iMhQAbzv_mcDdHZEgoonpbM7MjIW05OSeoEwEr",
      "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": "1742288870:67d7e66685dc14f5cccf7ef8",
          "password": "zDIbVEEWOF84HU3uYfrPLEcK2ts="
        }
      ]
    }
  }
}
danger

The links[gui] is the host link and should be kept a secret as it can be used to start the meeting.

info

The links[guest_join] can be shared and will guide people into a waiting room until the meeting is started.

id​

Type: STRING (required)
Default: RANDOM

Room id to get users into a specific meeting room.

warning

If omitted, the user will be alone in a new meeting room.

user[id]​

Type: STRING (optional)
Default: RANDOM

Custom 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.
Also see: User ID Behavior

user[name]​

Type: STRING (required)
Default:NULL

The display name that identifies the user in the meeting interface. This name will be shown in participant lists and user interface elements where participant identification is required.

user[avatar]​

Type: URL (optional)
Default: NULL

Link to the avatar image. Avatars will be displayed in the Prebuilt UI to show in the sidebar, as placeholder when camera is off and more.

The avatar should be a publicly accessible image file with square dimensions. For optimal display quality, use a 200×200 pixel PNG image.

Register Guest User​

Using the guest token received from the create room request, any number of guest users can be created. This provides an option for you to offer a join method to any meeting.

info

A guest link is only valid for the running meeting session. Once a meeting ends, the guest link perishes and cannot be used to join any future meetings in this room.

tip

It is a best practice to hand out guest links to call participants who are not part of your core team. They will only have access to the current meeting room session and not for any future ones - unless they get explicitly invited in real-time with a link.

POST /guests/`GUEST_TOKEN` # Create a guest user for a meeting.
RESPONSES 201 CREATED, 400 BAD REQUEST, 410 GONE, 423 LOCKED
REQUIRED name
RECOMMENDED id
Example Req/Res: Create a Guest User
Request
curl -X POST -H "Content-Type: application/json" -d "{ "name": "John Doe", "id": "johndoe"}" "https://api.eyeson.team/guests/$GUEST_TOKEN"
Response
{
  "access_key": "7fEiVaXhZXfho26NjcVaSeAD",
  "ready": false,
  "locked": false,
  "room": {
    "id": "janesroom",
    "name": "API magic",
    "ready": true,
    "started_at": "2025-03-17T09:54:24.388Z",
    "shutdown": false,
    "guest_token": "08TTSQkyD09JhVDqXrBISGly"
  },
  "team": {
    "name": "API magic"
  },
  "user": {
    "id": "johndoe",
    "room_id": "janesroom",
    "name": "John Doe",
    "avatar": null,
    "guest": true,
    "blocked": false,
    "ready": false
  },
  "links": {
    "self": "https://api.eyeson.team/rooms/7fEiVaXhZXfho26NjcVaSeAD",
    "gui": "https://app.eyeson.team/?7fEiVaXhZXfho26NjcVaSeAD",
    "guest_join": "https://app.eyeson.team/?guest=08TTSQkyD09JhVDqXrBISGly",
    "websocket": "https://api.eyeson.team/rt?access_key=7fEiVaXhZXfho26NjcVaSeAD"
  },
  "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": true,
    "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": "67d7f26e0b9fc24d6b206763",
      "conf_id": "67d7f150662b26dfda2ffd3f",
      "auth_token": "eyJhbGciOiJFUzM4NCJ9.eyJpc3MiOiJleWVzb24tY29tYXBpIiwiY2xpZW50X2lkIjoiNjdkN2YyNmUwYjlmYzI0ZDZiMjA2NzYzIiwiZXhwIjoxNzQyMjA5MTUwLCJjb25mX2lkIjoiNjdkN2YxNTA2NjJiMjZkZmRhMmZmZDNmIiwiYXVkIjoiZXllc29uLXNlcHAifQ.CJ7T6jyXE-bIs02_hJs618Pz57yD7FR_WBtZYpewi5CUpQ8C97uLvis8bmk46J7d0eG1e0rPa3vhu3cXrbV7TdGYIOmqXkxaczlkps9txoABxvTH3F4PMhN1a8UVi1B9",
      "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": "1742291950:67d7f26e0b9fc24d6b206763",
          "password": "32ZpgARvgAXYPqhc9iq/+3BaJ9E="
        }
      ]
    }
  }
}

id​

Type: STRING (optional)
User identifier

name​

Type: STRING (required)
Users name to be displayed in participants list.

avatar​

Type: URL (optional)
HTTP URI to a an avatar image shown in Prebuilt-UI.

custom_fields[locale]​

Type: Language Code (optional)
User preferred language code in Prebuilt-UI.
Valid values: en, de, fr

Kick User​

Sometimes it may be necessary to remove a participant from a meeting.

warning

Please be aware, that kicked users can re-join at any time! You will need to lock the room right after someone is kicked, to keep the user from rejoining.

DELETE /rooms/`ACCESS_KEY`/users/`USER_ID`
RESPONSES 200 OK, 403 FORBIDDEN, 404 NOT FOUND, 410 GONE
Example Req/Res: Kick User
Request
curl -X DELETE "https://api.eyeson.team/rooms/$ACCESS_KEY/users/$USER_ID"
Response
No Repsonse

If options[kick_available] is set to FALSE, related API requests will respond with status 403 FORBIDDEN.

User ID Behavior​

Cross-API Key Isolation​

  • User IDs from different API keys are completely isolated and will never collide
  • These are logically decoupled systems with no shared user ID namespace

User ID Behavior Within the Same API Key​

When using the same API key, the following rules apply:

Reusability​

  • A user ID previously used in any meeting can be reused in subsequent meetings
  • The same user ID can function as either a guest user or a generic user

Meeting Rules​

  1. Starting a new room: If a room is not running, any user ID can be used without conflicts, regardless of previous usage
  2. Joining existing rooms:
    • If a room is running and the user hasn't joined yet, they can join without conflicts
    • Rejoining: If rejoining the same running instance with the same user ID:
      • Will receive identical credentials as initial join
      • Must use the same access level (guest or generic user) as initial join
      • Attempting to join with a different access level will result in a Erro 409 Conflict.

Access Level Restrictions​

  • A single user ID cannot join a running meeting instance as both a guest and a generic user
  • When a meeting ends, these rules reset for the next meeting session