Permalink

The Permalink enables developers to pre-define meeting rooms, generate sharable guest links, and initiate meetings on demand.

Only registered hosts have the ability to initiate meetings. Guests cannot start meetings on their own and must wait for a host to begin the meeting before they can join.

All meeting room settings remain configurable throughout the lifetime of the permalink.

Create permalink

POST /permalink
HEADERS Authorization
RESPONSES 201 Created, 400 Bad Request, 401 Unauthorized, 503 Service Unavailable
REQUIRED user[name]
RECOMMENDED user[id], options[widescreen]

Example Req/Res: Create Permalink

Request
curl -X POST -H "Authorization: $API_KEY" \
    -H "Content-Type: application/json" \
    -d "{"user[name]": "John Doe", "user[id]": "johndoe", "options[widescreen]": true}" \
    "https://api.eyeson.team/permalink"

Response
{
    "permalink": {
        "id": "6643685b858f54f55edef723",
        "created_at": "2024-05-14T13:34:19.468Z",
        "user_token": "9clgjJXl1NzbcmF5vfXWhAVJ",
        "guest_token": "R2SdUxiqKhpBoUu0oi0pZZkZ",
        "expires_at": null
    },
    "room": {
        "id": "6643685b858f54f55edef723",
        "name": "Permalink Room",
        "started_at": null
    },
    "team": {
        "name": "Testers"
    },
    "user": {
        "id": "johndoe",
        "name": "John Doe",
        "avatar": null,
        "guest": false,
        "joined_at": "2024-05-14T13:34:19.468Z"
    },
    "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": "ptp",
        "layout_users": null,
        "layout_name": null,
        "layout_map": null,
        "voice_activation": false,
        "custom_fields": {},
        "widescreen": true,
        "background_color": "#121212"
    },
    "links": {
        "self": "https://api.eyeson.team/permalink/6643685b858f54f55edef723",
        "gui": "https://app.eyeson.team/permalink?9clgjJXl1NzbcmF5vfXWhAVJ",
        "guest_join": "https://app.eyeson.team/permalink?guest=R2SdUxiqKhpBoUu0oi0pZZkZ"
    }
}

warning

Please note that the room_id is ignored since it is created at runtime.

Find a list of useful parameters below. You can use all parameters from the start meeting action.

expires_at

Type: ISO8601 Timestamp (optional)
Optional Timestamp when permalink meetings can no longer be started. E.g. 2024-05-15T10:00:00.000Z

user[id]

Type: STRING (optional)
You can supply a custom user id to identify the user in further REST requests without the need of remembering the Eyeson user id e.g. your internal user id, an e-mail address, phone number, etc. If kept empty, a random id will be assigned.

user[name]

Type: STRING (required)
Display name of the user.

options[exit_url]

Type: URL (optional)
Exit destination, URL for exit button in Prebuilt-UI.

options[recording_available]

Type: BOOLEAN (optional)
Default: true
Allow recordings.

options[widescreen]

Type: BOOLEAN (optional)
Default: true
Run meeting in widescreen mode (16:9 aspect ratio).

options[custom_fields][locale]

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

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.

info

If you're using the GUI and Guest-join links, the Start meeting from permalink and Register guest user actions are handled automatically.

Get list of permalinks

GET /permalink
HEADERS Authorization
RESPONSES 200 OK, 401 Unauthorized

Example Req/Res: Get list of permalinks

Request
curl -X GET -H "Authorization: $API_KEY" "https://api.eyeson.team/permalink"

Response
{
    "page": 1,
    "limit": 25,
    "total": 3,
    "items": [
        {
            ... // see permalink object above
        },
        {
            ...
        },
        {
            ...
        }
    ]
}

page

Type: INTEGER (optional)
Fetch next set of permalinks

limit

Type: INTEGER (optional)
Default: 25

expired

Type: BOOLEAN (optional)
Omit for full list, true for only expired, false for only non-expired

Get specific permalink by Id

GET /permalink/`PERMALINK_ID`
HEADERS Authorization
RESPONSES 200 OK, 404 Not Found

Example Req/Res: Get specific Permalink by ID

Request
curl -X GET -H "Authorization: $API_KEY" "https://api.eyeson.team/permalink/$PERMALINK_ID"

Response
{
    "permalink": {
        "id": "6643685b858f54f55edef723",
        "created_at": "2024-05-14T13:34:19.468Z",
        "user_token": null,
        "guest_token": "R2SdUxiqKhpBoUu0oi0pZZkZ",
        "expires_at": null
    },
    "room": {
        "id": "6643685b858f54f55edef723",
        "name": "Test",
        "started_at": null
    },
    "team": {
        "name": "Test"
    },
    "user": null,
    "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": "ptp",
        "layout_users": null,
        "layout_name": null,
        "layout_map": null,
        "voice_activation": false,
        "custom_fields": {},
        "widescreen": true,
        "background_color": "#121212"
    },
    "links": {
        "self": "https://api.eyeson.team/permalink/6643685b858f54f55edef723",
        "gui": null,
        "guest_join": "https://app.eyeson.team/permalink?guest=R2SdUxiqKhpBoUu0oi0pZZkZ"
    }
}

warning

Please note that permalink.user_token, user, and links.gui are null, because the information is about the permalink and not the user.

Update permalink

PUT /permalink/`PERMALINK_ID`
HEADERS Authorization
RESPONSES 200 OK, 401 Unauthorized, 404 Not Found

Example Req/Res: Update Permalink

Request
curl -X PUT -H "Authorization: $API_KEY" "https://api.eyeson.team/permalink/$PERMALINK_ID"

Response
{
    "permalink": {
        "id": "6643685b858f54f55edef723",
        "created_at": "2024-05-14T13:34:19.468Z",
        "user_token": null,
        "guest_token": "R2SdUxiqKhpBoUu0oi0pZZkZ",
        "expires_at": null
    },
    "room": {
        "id": "6643685b858f54f55edef723",
        "name": "Test",
        "started_at": null
    },
    "team": {
        "name": "Test"
    },
    "user": null,
    "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": "ptp",
        "layout_users": null,
        "layout_name": null,
        "layout_map": null,
        "voice_activation": false,
        "custom_fields": {},
        "widescreen": true,
        "background_color": "#121212"
    },
    "links": {
        "self": "https://api.eyeson.team/permalink/6643685b858f54f55edef723",
        "gui": null,
        "guest_join": "https://app.eyeson.team/permalink?guest=R2SdUxiqKhpBoUu0oi0pZZkZ"
    }
}

Returns the updated permalink object. All parameters from Create Permalink can be adjusted.

Note that also expires_at can be adjusted.

Delete permalink

DELETE /permalink/`PERMALINK_ID`
HEADERS Authorization
RESPONSES 200 OK, 401 Unauthorized, 404 Not Found

Example Req/Res: Delete Permalink

Request
curl -X DELETE -H "Authorization: $API_KEY" "https://api.eyeson.team/permalink/$PERMALINK_ID"

Response

No Response

Register host user to permalink

Host users are allowed to start the meeting. Guests need to wait until a meeting is up and running.

POST /permalink/`PERMALINK_ID`/users
HEADERS Authorization
RESPONSES 201 Created, 400 Bad Request, 401 Unauthorized, 404 Not Found

Example Req/Res: Register host user to permalink

Request
curl -X POST -H "Authorization: $API_KEY" "https://api.eyeson.team/permalink/$PERMALINK_ID/users"

Response
{
    "permalink": {
        "id": "6643685b858f54f55edef723",
        "created_at": "2024-05-14T13:34:19.468Z",
        "user_token": "QTb1BqRO3YcwV6XmzhoVI7Wt",
        "guest_token": "R2SdUxiqKhpBoUu0oi0pZZkZ",
        "expires_at": null
    },
    "room": {
        "id": "6643685b858f54f55edef723",
        "name": "Test",
        "started_at": null
    },
    "team": {
        "name": "Test"
    },
    "user": {
        "id": "667a7cf6dfd92d8815fcfb31",
        "name": "Jane",
        "avatar": null,
        "guest": false,
        "joined_at": "2024-05-15T13:32:19.468Z"
    },
    "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": "ptp",
        "layout_users": null,
        "layout_name": null,
        "layout_map": null,
        "voice_activation": false,
        "custom_fields": {},
        "widescreen": true,
        "background_color": "#121212"
    },
    "links": {
        "self": "https://api.eyeson.team/permalink/6643685b858f54f55edef723",
        "gui": "https://app.eyeson.team/permalink?QTb1BqRO3YcwV6XmzhoVI7Wt",
        "guest_join": "https://app.eyeson.team/permalink?guest=R2SdUxiqKhpBoUu0oi0pZZkZ"
    }
}

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.

Remove host user from permalink

In case you need to revoke a USER_TOKEN or prevent a user from starting a meeting, the USER_TOKEN can be simply deleted.

warning

Once you remove the last host user, you must add a new host user to be able to start the meeting.

DELETE /permalink/`PERMALINK_ID`/users/`USER_TOKEN`
HEADERS Authorization
RESPONSES 200 OK, 401 Unauthorized, 404 Not Found

Example Req/Res: Remove host user from permalink

Request
curl -X DELETE -H "Authorization: $API_KEY" "https://api.eyeson.team/permalink/$PERMALINK_ID/users/$USER_TOKEN"

Response

No Response

Meeting information

Receive information about the room instance without authentication header.

Meeting Status

The room.started_at parameter indicates the current meeting status:

null: No meeting is currently running
ISO8601 Timestamp (e.g., 2024-05-14T13:34:19.468Z): A meeting is active and was started at the specified time

GET /permalink/`USER_TOKEN | GUEST_TOKEN`
RESPONSES 200 OK, 404 Not Found

Example Req/Res: Meeting Information

Request
curl -X GET "https://api.eyeson.team/permalink/$USER_TOKEN"

Response
{
    "permalink": {
        "id": "6643685b858f54f55edef723",
        "created_at": "2024-05-14T13:34:19.468Z",
        "user_token": null,
        "guest_token": "R2SdUxiqKhpBoUu0oi0pZZkZ",
        "expires_at": null
    },
    "room": {
        "id": "6643685b858f54f55edef723",
        "name": "Test",
        "started_at": null
    },
    "team": {
        "name": "Test"
    },
    "user": null,
    "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": "ptp",
        "layout_users": null,
        "layout_name": null,
        "layout_map": null,
        "voice_activation": false,
        "custom_fields": {},
        "widescreen": true,
        "background_color": "#121212"
    },
    "links": {
        "self": "https://api.eyeson.team/permalink/6643685b858f54f55edef723",
        "gui": null,
        "guest_join": "https://app.eyeson.team/permalinks?guest=R2SdUxiqKhpBoUu0oi0pZZkZ"
    }
}

Start meeting from permalink

Create a new meeting or join an existing via the permalink's USER_TOKEN.

POST /permalink/`USER_TOKEN`
RESPONSES 201 Created, 404 Not Found, 410 Gone, 503 Service Unavailable

Example Req/Res: Start Meeting from Permalink

Request
curl -X POST "https://api.eyeson.team/permalink/$USER_TOKEN"

Response
{
    "access_key": "aQrgsTQUn7HPZwncdFyolFNk",
    "ready": false,
    "locked": false,
    "room": {
        "id": "6643685b858f54f55edef723",
        "name": "Test",
        "ready": false,
        "started_at": "2024-05-14T13:44:54.436Z",
        "shutdown": false,
        "guest_token": "7dP90FgGlq39y4p9WqwhiyaL"
    },
    "team": {
        "name": "Test"
    },
    "user": {
        "id": "66436ad6858f54f55edef729",
        "room_id": "6643685b858f54f55edef723",
        "name": "Jane Doe",
        "avatar": null,
        "guest": false,
        "blocked": false,
        "ready": false
    },
    "links": {
        "self": "https://api.eyeson.team/rooms/aQrgsTQUn7HPZwncdFyolFNk",
        "gui": "https://app.eyeson.team/?aQrgsTQUn7HPZwncdFyolFNk",
        "guest_join": "https://app.eyeson.team/?guest=7dP90FgGlq39y4p9WqwhiyaL",
        "websocket": "https://api.eyeson.team/rt?access_key=aQrgsTQUn7HPZwncdFyolFNk"
    },
    "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": "ptp",
        "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": {
            ...
        }
    }
}

info

Returns the same response as POST /rooms.

Register guest user

Register any guest user when the meeting is up and running via the permalink's GUEST_TOKEN. Use the same endpoint as register guest user.

POST /guests/`GUEST_TOKEN`
RESPONSES 201 CREATED, 400 BAD REQUEST, 410 GONE, 423 LOCKED

Example Req/Res: Register Guest User

Request
curl -X POST "https://api.eyeson.team/guests/$GUEST_TOKEN"

Response
{
    "access_key": "9vevGllYKQ66LR8bV6u4Ygfe",
    "ready": false,
    "locked": false,
    "room": {
        "id": "6643685b858f54f55edef723",
        "name": "Test",
        "ready": false,
        "started_at": "2024-05-14T13:48:09.741Z",
        "shutdown": false,
        "guest_token": "VlokZmDfi6AvKseeKGrwUft6"
    },
    "team": {
        "name": "Test"
    },
    "user": {
        "id": "66436ba1858f54f55edef72c",
        "room_id": "6643685b858f54f55edef723",
        "name": "Guest",
        "avatar": null,
        "guest": true,
        "blocked": false,
        "ready": false
    },
    "links": {
        "self": "https://api.eyeson.team/rooms/9vevGllYKQ66LR8bV6u4Ygfe",
        "gui": "https://app.eyeson.team/?9vevGllYKQ66LR8bV6u4Ygfe",
        "guest_join": "https://app.eyeson.team/?guest=VlokZmDfi6AvKseeKGrwUft6",
        "websocket": "https://api.eyeson.team/rt?access_key=9vevGllYKQ66LR8bV6u4Ygfe"
    },
    "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": "ptp",
        "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": {
            ...
        }
    }
}

Create permalink​

expires_at​

user[id]​

user[name]​

options[exit_url]​

options[recording_available]​

options[widescreen]​

options[custom_fields][locale]​

Get list of permalinks​

page​

limit​

expired​

Get specific permalink by Id​

Update permalink​

Delete permalink​

Register host user to permalink​

Remove host user from permalink​

Meeting information​

Start meeting from permalink​

Register guest user​

Create permalink

expires_at

user[id]

user[name]

options[exit_url]

options[recording_available]

options[widescreen]

options[custom_fields][locale]

Get list of permalinks

page

limit

expired

Get specific permalink by Id

Update permalink

Delete permalink

Register host user to permalink

Remove host user from permalink

Meeting information

Start meeting from permalink

Register guest user