--- title: Lobby Resource sidebarTitle: Lobby description: Reference for Discord lobby objects used for matchmaking. --- import {ManualAnchor} from '/snippets/manualanchor.jsx' import {Route} from '/snippets/route.jsx' ### Lobby Object Represents a lobby within Discord. See [Managing Lobbies](/developers/discord-social-sdk/development-guides/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\ | dictionary of string key/value pairs. The max total length is 1000. | | members | array of [lobby member](/developers/resources/lobby#lobby-member-object) 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\ | dictionary of string key/value pairs. The max total length is 1000. | | flags? | integer | [lobby member flags](/developers/resources/lobby#lobby-member-object-lobby-member-flags) combined as a [bitfield](https://en.wikipedia.org/wiki/Bit_field) | | 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](/developers/resources/lobby#lobby-object) object. [Discord Social SDK](/developers/discord-social-sdk/overview) clients will not be able to join or leave a lobby created using this API, such as [`Client::CreateOrJoinLobby`]. See [Managing Lobbies](/developers/discord-social-sdk/development-guides/managing-lobbies#server-side-lobby-management) for more information. ### JSON Params | Field | Type | Description | |-----------------------|----------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | metadata? | ?dict\ | optional dictionary of string key/value pairs. The max total length is 1000. | | members? | array of [lobby member](/developers/resources/lobby#lobby-member-object) objects | optional array of up to 25 users to be added to the lobby. Requests with more than 25 members are rejected. See [Member Limits](/developers/resources/lobby#create-lobby-member-limits). | | 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. | ###### Member Limits Up to 25 members can be included in a single request. The array is not truncated. A request with more than 25 members fails with a `400` response and error code `50035` (`Invalid Form Body`), with a `BASE_TYPE_MAX_LENGTH` error on `members` in the [`errors` object](/developers/reference#error-messages). A lobby can still hold up to 1,000 members. Add more with [Add a Member to a Lobby](/developers/resources/lobby#add-a-member-to-a-lobby), or in batches of up to 25 with [Bulk Update Lobby Members](/developers/resources/lobby#bulk-update-lobby-members). #### Lobby Member JSON Params | Field | Type | Description | |------------------|-------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | id | snowflake | Discord user id of the user to add to the lobby | | metadata? | ?dict\ | optional dictionary of string key/value pairs. The max total length is 1000. | | flags? | integer | [lobby member flags](/developers/resources/lobby#lobby-member-object-lobby-member-flags) combined as a [bitfield](https://en.wikipedia.org/wiki/Bit_field) | | 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`](/developers/discord-social-sdk/core-concepts/oauth2-scopes#default-communication-scopes) scope. Returns a [lobby](/developers/resources/lobby#lobby-object) 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\ | 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\ | 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\}](/developers/resources/lobby#lobby-object) Returns a [lobby](/developers/resources/lobby#lobby-object) object for the specified lobby id, if it exists. ## Modify Lobby /lobbies/[\{lobby.id\}](/developers/resources/lobby#lobby-object) Modifies the specified lobby with new values, if provided. Returns the updated [lobby](/developers/resources/lobby#lobby-object) object. ### JSON Params | Field | Type | Description | |-----------------------|----------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | metadata? | ?dict\ | optional dictionary of string key/value pairs. The max total length is 1000. Overwrites any existing metadata. | | members? | array of [lobby member](/developers/resources/lobby#lobby-member-object) 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](/developers/resources/lobby#lobby-member-json-params) for the accepted fields and [Member Limits](/developers/resources/lobby#create-lobby-member-limits) for the per-request cap. | | 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\}](/developers/resources/lobby#lobby-object) 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\}](/developers/resources/lobby#lobby-object)/members/[\{user.id\}](/developers/resources/user#user-object) 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](/developers/resources/lobby#lobby-member-object) object. ### JSON Params | Field | Type | Description | |------------------|-------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | metadata? | ?dict\ | optional dictionary of string key/value pairs. The max total length is 1000. | | flags? | integer | [lobby member flags](/developers/resources/lobby#lobby-member-object-lobby-member-flags) combined as a [bitfield](https://en.wikipedia.org/wiki/Bit_field) | | 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\}](/developers/resources/lobby#lobby-object)/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](/developers/resources/lobby#lobby-member-object) 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. Requests with more than 25 members fail with a `400` response and error code `50035` (`Invalid Form Body`). | Field | Type | Description | |------------------|-------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | id | snowflake | Discord user id of the user to add, update, or remove | | metadata? | ?dict\ | optional dictionary of string key/value pairs. The max total length is 1000. | | flags? | integer | [lobby member flags](/developers/resources/lobby#lobby-member-object-lobby-member-flags) combined as a [bitfield](https://en.wikipedia.org/wiki/Bit_field) | | 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\}](/developers/resources/lobby#lobby-object)/members/[\{user.id\}](/developers/resources/user#user-object) 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\}](/developers/resources/lobby#lobby-object)/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\}](/developers/resources/lobby#lobby-object)/channel-linking Links an existing text channel to a lobby. See [Linked Channels](/developers/discord-social-sdk/development-guides/linked-channels) for more information. Uses `Bearer` token for authorization and user must be a lobby member with `CanLinkLobby` [lobby member flag](/developers/resources/lobby#lobby-member-object-lobby-member-flags). Returns a [lobby](/developers/resources/lobby#lobby-object) 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\}](/developers/resources/lobby#lobby-object)/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](/developers/resources/lobby#lobby-member-object-lobby-member-flags). Returns a [lobby](/developers/resources/lobby#lobby-object) object without a linked channel. ## Send Lobby Message /lobbies/[\{lobby.id\}](/developers/resources/lobby#lobby-object)/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`](/developers/discord-social-sdk/core-concepts/oauth2-scopes#default-communication-scopes) scope. Returns the created lobby message object. If the lobby has a [linked channel](/developers/discord-social-sdk/development-guides/linked-channels), the message is also forwarded to that channel. If forwarding fails (for example, due to AutoMod), the lobby message is still delivered to other lobby members. ### JSON Params | Field | Type | Description | |-----------|-------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------| | content | string | message content. Must be non-empty. | | metadata? | ?dict\ | 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](https://en.wikipedia.org/wiki/Bit_field). 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](/developers/resources/message#message-object-message-types) | | 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](/developers/resources/user#user-object) who sent the message | | lobby_member? | object | contains a single `additional_name` string — the author's [lobby member](/developers/resources/lobby#lobby-member-object) additional display name, captured when the message was sent. Omitted if the author had no `additional_name` set. | | metadata? | ?dict\ | dispatch-only metadata sent with the message | | moderation_metadata? | ?dict\ | moderation metadata set via [Update Lobby Message Moderation Metadata](/developers/resources/lobby#update-lobby-message-moderation-metadata) | | flags | integer | [message flags](/developers/resources/message#message-object-message-flags) bitfield | | application_id | snowflake | the application that sent the message | ## Get Lobby Messages /lobbies/[\{lobby.id\}](/developers/resources/lobby#lobby-object)/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`](/developers/discord-social-sdk/core-concepts/oauth2-scopes#default-communication-scopes) scope. Returns an array of lobby message objects (see [Send Lobby Message](/developers/resources/lobby#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\}](/developers/resources/lobby#lobby-object)/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](/developers/discord-social-sdk/how-to/integrate-moderation#server-side-chat-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\}](/developers/resources/lobby#lobby-object)/members/@me/invites Creates a single-use guild invite to the lobby's [linked channel](/developers/discord-social-sdk/development-guides/linked-channels), 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`](/developers/discord-social-sdk/core-concepts/oauth2-scopes#default-communication-scopes) scope. Returns a [lobby invite object](/developers/resources/lobby#lobby-invite-object). ## Create Lobby Channel Invite for User /lobbies/[\{lobby.id\}](/developers/resources/lobby#lobby-object)/members/[\{user.id\}](/developers/resources/user#user-object)/invites Creates a single-use guild invite to the lobby's [linked channel](/developers/discord-social-sdk/development-guides/linked-channels) 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](/developers/resources/lobby#lobby-invite-object). ###### Lobby Invite Object | Field | Type | Description | |-------|--------|----------------------------------------------------------------------------------------------| | code | string | the [invite](/developers/resources/invite#invite-object) code for the lobby's linked channel | ## Development Rate Limits Applications without [increased rate limits for production releases](/developers/discord-social-sdk/core-concepts/communication-features#applying-for-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 are per-application rate limits, not per-user. These limitations are designed to provide sufficient capacity for development, testing, and small-scale demos while ensuring system stability. --- ## Change Log | Date | Changes | |-------------------|---------------------------------------------------------------------------------------------------------------------------| | November 16, 2026 | Document that more than 25 members on Create Lobby, Modify Lobby, and Bulk Update Lobby Members is rejected with HTTP 400 | | August 12, 2026 | `additional_name` can now be set via Create Lobby and Modify Lobby | {/* Autogenerated Reference Links */} [`Client::CreateOrJoinLobby`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#acef978faffe9ac736613810d9655cdf8 [`LobbyHandle`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1LobbyHandle.html#a04cebab69ab0e7fb930346a14a87e843 [`MessageHandle::AdditionalName`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1MessageHandle.html#a8158f30352e827c32d44f3172b4a0890