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, 423 LOCKED
REQUIRED user[name]
RECOMMENDED user[id], options[widescreen]

Example Req/Res: Create Permalink

curl
node sdk
go sdk
php sdk

curl -X POST \
  -H "Authorization: $API_KEY" \
  -d "user[id]=johndoe" \
  -d "user[name]=John Doe" \
  -d "options[widescreen]=true" \
  "https://api.eyeson.team/permalink"

const apiKey = '...';
const eyeson = new Eyeson({ apiKey });
const permalink = await eyeson.permalink.create('John Doe', {
    user: { id: 'johndoe' },
    options: { widescreen: true },
});

// TBD

$apiKey = '...';
$eyeson = new Eyeson($apiKey);
$permalink = $eyeson->permalink->create('John Doe', [
    'user' => ['id' => 'johndoe'],
    'widescreen' => true
]);

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, 423 LOCKED

Example Req/Res: Get list of permalinks

curl
node sdk
go sdk
php sdk

curl -X GET \
  -H "Authorization: $API_KEY" \
  "https://api.eyeson.team/permalink?expired=false"

const apiKey = '...';
const eyeson = new Eyeson({ apiKey });
const list = await eyeson.permalink.getAll({ expired: false });

// TBD

$apiKey = '...';
$eyeson = new Eyeson($apiKey);
$list = $eyeson->permalink->getAll(['expired' => false]);

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

page

Type: INTEGER (optional)
Default: 1

Specifies the results page to fetch (up to 25 permalinks per page).
This parameter uses 1-based indexing, meaning the first page is 1, second page is 2, etc. Must be greater than 0.

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, 423 LOCKED

Example Req/Res: Get specific Permalink by ID

curl
node sdk
go sdk
php sdk

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

const apiKey = '...';
const permalinkId = '...';
const eyeson = new Eyeson({ apiKey });
const permalink = await eyeson.permalink.getbyId(permalinkId);

// TBD

$apiKey = '...';
$permalinkId = '...';
$eyeson = new Eyeson($apiKey);
$permalink = $eyeson->permalink->getById($permalinkId);

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, 423 LOCKED

Example Req/Res: Update Permalink

curl
node sdk
go sdk
php sdk

curl -X PUT \
  -H "Authorization: $API_KEY" \
  -d "options[widescreen]=false" \
  "https://api.eyeson.team/permalink/$PERMALINK_ID"

const apiKey = '...';
const permalinkId = '...';
const eyeson = new Eyeson({ apiKey });
const permalink = await eyeson.permalink.update(permalinkId, {
    options: { widescreen: false },
});

// TBD

$apiKey = '...';
$permalinkId = '...';
$eyeson = new Eyeson($apiKey);
$permalink = $eyeson->permalink->update($permalinkId, [
    'widescreen' => false
]);

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, 423 LOCKED

Example Req/Res: Delete Permalink

curl
node sdk
go sdk
php sdk

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

const apiKey = '...';
const permalinkId = '...';
const eyeson = new Eyeson({ apiKey });
await eyeson.permalink.delete(permalinkId);

// TBD

$apiKey = '...';
$permalinkId = '...';
$eyeson = new Eyeson($apiKey);
$eyeson->permalink->delete($permalinkId);

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, 423 LOCKED

Example Req/Res: Register host user to permalink

curl
node sdk
go sdk
php sdk

curl -X POST \
  -H "Authorization: $API_KEY" \
  -d "user[name]=Jane" \
  "https://api.eyeson.team/permalink/$PERMALINK_ID/users"

const apiKey = '...';
const permalinkId = '...';
const eyeson = new Eyeson({ apiKey });
const permalink = await eyeson.permalink.addUser(permalinkId, 'Jane');

// TBD

$apiKey = '...';
$permalinkId = '...';
$eyeson = new Eyeson($apiKey);
$permalink = $eyeson->permalink->addUser($permalinkId, 'Jane');

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, 423 LOCKED

Example Req/Res: Remove host user from permalink

curl
node sdk
go sdk
php sdk

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

const apiKey = '...';
const permalinkId = '...';
const userToken = '...';
const eyeson = new Eyeson({ apiKey });
await eyeson.permalink.removeUser(permalinkId, userToken);

// TBD

$apiKey = '...';
$permalinkId = '...';
$userToken = '...';
$eyeson = new Eyeson($apiKey);
$eyeson->permalink->removeUser($permalinkId, $userToken);

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

curl
node sdk
go sdk
php sdk

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

const apiKey = '...';
const userToken = '...';
const eyeson = new Eyeson({ apiKey });
const user = await eyeson.permalink.joinMeeting(userToken);

// TBD

$apiKey = '...';
$userToken = '...';
$eyeson = new Eyeson($apiKey);
$room = $eyeson->permalink->joinMeeting($userToken);

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

curl
node sdk
go sdk
php sdk

export GUEST_TOKEN=...
curl -X POST \
  -d "user[name]=Guest" \
  "https://api.eyeson.team/guests/$GUEST_TOKEN"

const apiKey = '...';
const guestToken = '...';
const eyeson = new Eyeson({ apiKey });
const guest = await eyeson.permalink.registerGuest('Guest', guestToken);

apiKey := "..."
guestToken := "..."
client, _ := eyeson.NewClient(apiKey)
userService, _ := client.Rooms.GuestJoin(guestToken, nil, "Guest")

$apiKey = '...';
$guestToken = '...';
$eyeson = new Eyeson($apiKey);
$room = $eyeson->permalink->registerGuest('Guest', $guestToken);

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