Lobby Resource

Lobby Object

Represents a lobby within Discord. See Managing Lobbies for more information.

Lobby Structure

Field	Type	Description
id	snowflake	the id of this channel
application_id	snowflake	application that created the lobby
metadata	?dict<string, string>	dictionary of string key/value pairs. The max total length is 1000.
members	array of lobby member objects	members of the lobby
linked_channel?	channel object	the guild channel linked to the lobby

Lobby Member Object

Represents a member of a lobby, including optional metadata and flags.

Lobby Member Structure

Field	Type	Description
id	snowflake	the id of the user
metadata?	?dict<string, string>	dictionary of string key/value pairs. The max total length is 1000.
flags?	integer	lobby member flags combined as a bitfield
additional_name?	string	an additional 1-80 character display name for the member, such as an in-game character name. Can only be set through the HTTP API, not from a Social SDK client. Accessible via the Social SDK with `MessageHandle::AdditionalName`

Lobby Member Flags

Flag	Value	Description
CanLinkLobby	`1<<0`	user can link a text channel to a lobby

Example Lobby Object

JSON

{
  "id": "96008815106887111",
  "application_id": "41771983429993937",
  "metadata": {
    "topic": "we need more redstone"
  },
  "members": [
    {
      "id": "41771983429993000",
      "metadata": null,
      "flags": 1,
      "additional_name": "Twindly Shimmerleaf"
    }
  ]
}

Create Lobby

/lobbies

Creates a new lobby, adding any of the specified members to it, if provided.

Returns a lobby object.

JSON Params

Field	Type	Description
metadata?	?dict<string, string>	optional dictionary of string key/value pairs. The max total length is 1000.
members?	array of lobby member objects	optional array of up to 25 users to be added to the lobby
idle_timeout_seconds?	integer	seconds to wait before shutting down a lobby after it becomes idle. Value can be between 5 and 604800 (7 days). See `LobbyHandle` for more details on this behavior.

Lobby Member JSON Params

Field	Type	Description
id	snowflake	Discord user id of the user to add to the lobby
metadata?	?dict<string, string>	optional dictionary of string key/value pairs. The max total length is 1000.
flags?	integer	lobby member flags combined as a bitfield
additional_name?	?string	an additional display name for the member, such as an in-game character name. 1-80 characters. When updating an existing member, omit the field to preserve their current value, or send `null` to clear it.

Create or Join Lobby

/lobbies

Creates a new lobby for the application identified by a secret, or joins the calling user to the existing lobby with that secret if one already exists. Updates lobby metadata and the calling member's metadata on join.

Uses Bearer token for authorization with the sdk.social_layer scope.

Returns a lobby object.

JSON Params

Field	Type	Description
secret	string	secret used to identify the lobby. If a lobby for this application already exists with this secret, the caller joins it; otherwise a new lobby is created. Max 250 characters.
idle_timeout_seconds?	integer	seconds to wait before shutting down a lobby after it becomes idle. Value can be between 5 and 604800 (7 days). See `LobbyHandle` for more details on this behavior.
lobby_metadata?	?dict<string, string>	optional dictionary of string key/value pairs to set on the lobby. The max total length is 1000. Overwrites any existing lobby metadata.
member_metadata?	?dict<string, string>	optional dictionary of string key/value pairs to set on the calling user's lobby member. The max total length is 1000.

Get Lobby

/lobbies/{lobby.id}

Returns a lobby object for the specified lobby id, if it exists.

Modify Lobby

/lobbies/{lobby.id}

Modifies the specified lobby with new values, if provided.

Returns the updated lobby object.

JSON Params

Field	Type	Description
metadata?	?dict<string, string>	optional dictionary of string key/value pairs. The max total length is 1000. Overwrites any existing metadata.
members?	array of lobby member objects	optional array of up to 25 users to replace the lobby members with. If provided, lobby members not in this list will be removed from the lobby. See Lobby Member JSON Params for the accepted fields.
idle_timeout_seconds?	integer	seconds to wait before shutting down a lobby after it becomes idle. Value can be between 5 and 604800 (7 days). See `LobbyHandle` for more details on this behavior.

Delete Lobby

/lobbies/{lobby.id}

Deletes the specified lobby if it exists.

It is safe to call even if the lobby is already deleted as well.

Returns nothing.

Add a Member to a Lobby

/lobbies/{lobby.id}/members/{user.id}

Adds the provided user to the specified lobby. If called when the user is already a member of the lobby will update fields such as metadata on that user instead.

Returns the lobby member object.

JSON Params

Field	Type	Description
metadata?	?dict<string, string>	optional dictionary of string key/value pairs. The max total length is 1000.
flags?	integer	lobby member flags combined as a bitfield
additional_name?	?string	an additional display name for the member, such as an in-game character name. 1-80 characters. Omit the field to preserve the member's current value, or send `null` to clear it.

Bulk Update Lobby Members

/lobbies/{lobby.id}/members/bulk

Adds, updates, or removes up to 25 members from the specified lobby in a single request. Members with remove_member: false (the default) are upserted — added if not present, or updated with the provided metadata and flags if already a member. Members with remove_member: true are removed.

Returns an array of lobby member objects for the upserted members. Removed members are not included in the response.

JSON Params

An array of member objects. Minimum 1, maximum 25.

Field	Type	Description
id	snowflake	Discord user id of the user to add, update, or remove
metadata?	?dict<string, string>	optional dictionary of string key/value pairs. The max total length is 1000.
flags?	integer	lobby member flags combined as a bitfield
additional_name?	?string	an additional display name for the member, such as an in-game character name. 1-80 characters. Omit the field to preserve the member's current value, or send `null` to clear it.
remove_member?	boolean	if `true`, the user is removed from the lobby instead of upserted. Default `false`.

Remove a Member from a Lobby

/lobbies/{lobby.id}/members/{user.id}

Removes the provided user from the specified lobby. It is safe to call this even if the user is no longer a member of the lobby, but will fail if the lobby does not exist.

Returns nothing.

Leave Lobby

/lobbies/{lobby.id}/members/@me

Removes the current user from the specified lobby. It is safe to call this even if the user is no longer a member of the lobby, but will fail if the lobby does not exist.

Uses Bearer token for authorization.

Returns nothing.

Link Channel to Lobby

/lobbies/{lobby.id}/channel-linking

Links an existing text channel to a lobby. See Linked Channels for more information.

Uses Bearer token for authorization and user must be a lobby member with CanLinkLobby lobby member flag.

Returns a lobby object with a linked channel.

JSON Params

Field	Type	Description
channel_id?	snowflake	the id of the channel to link to the lobby. If not provided, will unlink any currently linked channels from the lobby.

Unlink Channel from Lobby

/lobbies/{lobby.id}/channel-linking

Unlinks any currently linked channels from the specified lobby.

Send a request to this endpoint with an empty body to unlink any currently linked channels from the specified lobby.

Uses Bearer token for authorization and user must be a lobby member with CanLinkLobby lobby member flag.

Returns a lobby object without a linked channel.

Send Lobby Message

/lobbies/{lobby.id}/messages

Sends a message to the specified lobby. The calling user must be a member of the lobby.

Uses Bearer token for authorization with the sdk.social_layer scope.

Returns the created lobby message object.

JSON Params

Field	Type	Description
content	string	message content. Must be non-empty.
metadata?	?dict<string, string>	optional dictionary of string key/value pairs delivered alongside the message to active clients via the Social SDK. Not persisted on the linked channel message.
flags?	integer	optional message flags combined as a bitfield. Only flags creatable by the Social SDK are accepted.

Lobby Message Object

Field	Type	Description
id	snowflake	id of the message
type	integer	message type
content	string	message content
lobby_id	snowflake	id of the lobby this message was sent to
channel_id	snowflake	included for compatibility with the messages interface; equal to `lobby_id`
author	user object	the user who sent the message
lobby_member?	object	contains a single `additional_name` string — the author's lobby member additional display name, captured when the message was sent. Omitted if the author had no `additional_name` set.
metadata?	?dict<string, string>	dispatch-only metadata sent with the message
moderation_metadata?	?dict<string, string>	moderation metadata set via Update Lobby Message Moderation Metadata
flags	integer	message flags bitfield
application_id	snowflake	the application that sent the message

Get Lobby Messages

/lobbies/{lobby.id}/messages

Returns the most recent messages in the specified lobby. The calling user must be a member of the lobby.

Uses Bearer token for authorization with the sdk.social_layer scope.

Returns an array of lobby message objects (see Send Lobby Message for the object shape).

Query Params

Field	Type	Description
limit?	integer	max number of messages to return (1-200). Defaults to 50.

Update Lobby Message Moderation Metadata

/lobbies/{lobby.id}/messages/{message.id}/moderation-metadata

Sets the moderation metadata for a lobby message. The metadata is app-scoped and delivered to active game clients via the Social SDK as a realtime message update. See Integrate Moderation for the full moderation flow.

Uses Bot token for authorization.

Returns HTTP 204: No Content on success.

JSON Params

Field	Type	Description
*	string	Free-form key–value pairs describing the moderation decision. Up to 5 keys; key length ≤ 1024 characters; value length ≤ 2000 characters.

Create Lobby Channel Invite for Self

/lobbies/{lobby.id}/members/@me/invites

Creates a single-use guild invite to the lobby's linked channel, targeted at the calling user. The lobby must have a linked channel and the caller must be a member of the lobby. The invite expires after one hour.

Uses Bearer token for authorization with the sdk.social_layer scope.

Returns a lobby invite object.

Create Lobby Channel Invite for User

/lobbies/{lobby.id}/members/{user.id}/invites

Creates a single-use guild invite to the lobby's linked channel on behalf of an application, targeted at the specified user. The lobby must have a linked channel. The invite expires after one hour.

Uses Bot token for authorization.

Returns a lobby invite object.

Lobby Invite Object

Field	Type	Description
code	string	the invite code for the lobby's linked channel

Development Rate Limits

Applications without increased rate limits for production releases are subject to the following application-wide development limits:

Endpoint	Limit
`POST /lobbies`	100 per 2 hours
`PUT /lobbies`	100 per 2 hours
`PATCH /lobbies/{lobby.id}`	100 per 2 hours
`PUT /lobbies/{lobby.id}/members/{user.id}`	100 per 2 hours
`DELETE /lobbies/{lobby.id}/members/{user.id}`	100 per 2 hours
`POST /lobbies/{lobby.id}/members/bulk`	100 per 2 hours
`POST /lobbies/{lobby.id}/members/@me/invites`	100 per 2 hours
`POST /lobbies/{lobby.id}/members/{user.id}/invites`	100 per 2 hours
`PATCH /lobbies/{lobby.id}/channel-linking`	20 per 2 hours
`POST /lobbies/{lobby.id}/messages`	100 per 2 hours

These limitations are designed to provide sufficient capacity for development, testing, and small-scale demos while ensuring system stability.

Change Log

Date	Changes
August 12, 2026	`additional_name` can now be set via Create Lobby and Modify Lobby