https://livekit.io logo
Join Slack
Powered by
in the livekit token whats the difference between ...
# ask-ai
w
in the livekit token whats the difference between person attribute vs metadata
t
Thanks for reaching out, Jimmy. I'm an AI assistant and I'm here to help. Give me a moment while I research this topic.
Thanks — great question. You're right to ask for clarification. Short answer • There is no "person" attribute in a LiveKit token. The fields you’ll commonly see that relate to a participant are 
identity
, 
name
, and 
metadata
. What each field is for • 
identity
(required): A unique string that identifies the participant in a room. LiveKit enforces uniqueness — only one connection can use a given identity at a time. • 
name
(optional): A human-readable display name for the participant (for UI/display purposes only). It’s not used for uniqueness or access control. • 
metadata
(optional): A string you can use to pass arbitrary app-specific data (often JSON). LiveKit treats this as opaque and forwards it to clients; use it for roles, preferences, or other context your app needs. When to use which • Use 
identity
as the canonical user identifier for connection/session logic. • Use 
name
for showing a friendly name in your UI. • Use 
metadata
when you need to attach custom structured information to the participant that your application or other clients will read. If you meant something else by “person” (for example a custom object you’re including in your app-side token creation), tell me how you’re building tokens and I’ll suggest the best field to use. Sources: server-sdk-js | livekit/livekit_composite | DeepWiki | Server-side | livekit/livekit_composite | DeepWiki
w
sorry i mean Participant attributes
t
Thanks for the clarification — that helps. Short answer • Participant attributes are key-value pairs (
map[string]string
) attached to a participant and synced across the room. • Metadata is a single string (often JSON) attached to a participant and also synced across the room. What participant attributes are • Stored as key-value string pairs (e.g., 
"role": "moderator"
, 
"team": "sales"
). • Designed for dynamic, granular state you may update often. • You can set them in the access token when generating it or update them server-side after the participant has joined. • When attributes change, clients receive 
participant_attributes_changed
events so your UI/logic can react in real time. • Attributes are convenient for routing, feature flags, roles, or any small pieces of state you want to change individually. What metadata is • A single string field (commonly used to hold JSON). • Best for passing opaque or structured payloads that your application reads as a whole (e.g., profile JSON or initial context). • When metadata changes, clients receive 
participant_metadata_changed
events. • Updating metadata replaces the entire string (no per-key updates). When to use which • Use attributes for frequently-updated, discrete pieces of participant state (roles, teams, flags). • Use metadata for a single blob of information you treat as one object (profile, settings bundle) or for richer structured data you don’t need to update piecemeal. How to set them (examples) 1. In token generation (JS example — attributes included in the grant)
Copy code
const at = new AccessToken('api-key', 'secret');
at.identity = 'user-123';
at.addGrant({
  roomJoin: true,
  room: 'my-room',
  attributes: {
    'role': 'moderator',
    'location': 'NYC'
  }
});
1. Setting metadata on the token
Copy code
token.setMetadata('{"userId":"123","name":"Alice"}');
If you want, tell me: • How you plan to use the data (roles, UI name, routing, profile data), and I’ll recommend which to use and give a sample pattern for token generation and server-side updates. Sources: livekit/livekit_composite | DeepWiki | Job lifecycle | LiveKit Documentation | server-sdk-ruby | livekit/livekit_composite | DeepWiki | How to do call transfers with Five9 | LiveKit
Open in Slack
PreviousNext
Powered by