Rooms, participants and roles

The three nouns every call is made of, and the three roles a participant can hold.

Three nouns, and then a fourth thing that is not a noun but decides everything: the role.

Room#

A named space on one media server. It exists because something asked for it and it stops existing when the last participant leaves or something ends it.

The name is the identity. Two callers who use the same room name are in the same call — start_call with an existing room name joins that call rather than starting a second one. That is occasionally what you want and is more often a bug, so room names should carry something unique.

A room lives on exactly one region's media server. There is no cross-region room; see Regions.

Participant#

Anything in a room: a browser, an agent worker, a rendered avatar, a phone line. Each has an identity, which you choose, and which is what the other participants see.

Identity is not authentication. It is a label inside one call, asserted by the token; the token is the thing that was verified. Two participants cannot hold the same identity in one room — the second one displaces the first.

Track#

A stream a participant publishes: microphone audio, camera video, screen share, or a data channel. Other participants subscribe to the ones they want.

Most of what a client does with tracks is LiveKit's own API, and this site does not restate it — see their transport docs (opens in a new tab). What LiveGrid decides is whether you may publish one, which is the role.

The three roles#

A role is a named bundle of permissions. A caller asks for a role by name and the kit builds the grant; a caller never assembles its own, because a caller that could would be able to hand a browser participant the right to publish data and drive the agent.

Role	Can be heard	Can subscribe	`canPublishData`	For
`human`	yes	yes	no	the person on the call
`observer`	no	yes	no	supervision, QA, a live transcript view
`agent`	yes	yes	yes	the worker

Two failure modes worth naming, because both are silent:

A worker minted as human joins fine and then never speaks. Agent control messages travel over the data channel, and without canPublishData they are dropped with no error the worker can see.
An observer who was meant to participate appears in the room and is inaudible. Subscribe-only is the whole point of the role, and from the observer's side it looks exactly like a broken microphone.

Full parameters on Access tokens and grants.