Documentation Index
Fetch the complete documentation index at: https://docs.discord.com/llms.txt
Use this file to discover all available pages before exploring further.
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 |
Lobby Member Flags
| Flag | Value | Description |
|---|
| CanLinkLobby | 1<<0 | user can link a text channel to a lobby |
Example Lobby Object
{
"id": "96008815106887111",
"application_id": "41771983429993937",
"metadata": {
"topic": "we need more redstone",
},
"members": [
{
"id": "41771983429993000",
"metadata": null,
"flags": 1
}
]
}
Create Lobby
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 |
Get Lobby
Returns a lobby object for the specified lobby id, if it exists.
Modify Lobby
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. |
| 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
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
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 |
Bulk Update Lobby Members
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.
Users unknown to Discord will return a 404 UNKNOWN_USER error. Users that fail permission checks or who have already reached the maximum number of lobbies per application (and are not already a member of this lobby) are silently dropped from the upsert set.
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 |
| remove_member? | boolean | if true, the user is removed from the lobby instead of upserted. Default false. |
Remove a Member from a Lobby
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
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
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
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.
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. |
Development Rate Limits
Applications without increased rate limits for production releases are subject to the following application-wide development limits:
| Endpoint | Limit |
|---|
POST /lobbies | 20 per 2 hours |
PUT /lobbies | 20 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 |
PATCH /lobbies/{lobby.id}/channel-linking | 20 per 2 hours |
POST /lobbies/{lobby.id}/messages | 100 per 2 hours |
These are per-application rate limits, not per-user.
