# Lobby Resource ### Lobby Object Represents a lobby within Discord. See [Managing Lobbies](/guides/lobbies-voice-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](/guides/http-api-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](/guides/http-api-resources-lobby#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](/guides/http-api-resources-lobby#lobby-object) object. :::callout{intent="info"} [Discord Social SDK](/guides/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](/guides/lobbies-voice-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](/guides/http-api-resources-lobby#lobby-member-object) 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\ | optional dictionary of string key/value pairs. The max total length is 1000. | | flags? | integer | [lobby member flags](/guides/http-api-resources-lobby#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`](/guides/core-concepts-oauth2-scopes#default-communication-scopes) scope. Returns a [lobby](/guides/http-api-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}](/guides/http-api-resources-lobby#lobby-object) Returns a [lobby](/guides/http-api-resources-lobby#lobby-object) object for the specified lobby id, if it exists. ## Modify Lobby /lobbies/[{lobby.id}](/guides/http-api-resources-lobby#lobby-object) Modifies the specified lobby with new values, if provided. Returns the updated [lobby](/guides/http-api-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](/guides/http-api-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](/guides/http-api-resources-lobby#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}](/guides/http-api-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}](/guides/http-api-resources-lobby#lobby-object)/members/[{user.id}](/guides/http-api-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](/guides/http-api-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](/guides/http-api-resources-lobby#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}](/guides/http-api-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](/guides/http-api-resources-lobby#lobby-member-object) objects for the upserted members. Removed members are not included in the response. :::callout{intent="info"} 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\ | optional dictionary of string key/value pairs. The max total length is 1000. | | flags? | integer | [lobby member flags](/guides/http-api-resources-lobby#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}](/guides/http-api-resources-lobby#lobby-object)/members/[{user.id}](/guides/http-api-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}](/guides/http-api-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}](/guides/http-api-resources-lobby#lobby-object)/channel-linking Links an existing text channel to a lobby. See [Linked Channels](/guides/lobbies-voice-development-guides-linked-channels) for more information. Uses `Bearer` token for authorization and user must be a lobby member with `CanLinkLobby` [lobby member flag](/guides/http-api-resources-lobby#lobby-member-flags). Returns a [lobby](/guides/http-api-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}](/guides/http-api-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](/guides/http-api-resources-lobby#lobby-member-flags). Returns a [lobby](/guides/http-api-resources-lobby#lobby-object) object without a linked channel. ## Send Lobby Message /lobbies/[{lobby.id}](/guides/http-api-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`](/guides/core-concepts-oauth2-scopes#default-communication-scopes) scope. Returns the created lobby message object. :::callout{intent="info"} If the lobby has a [linked channel](/guides/lobbies-voice-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](/guides/http-api-resources-message#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](/guides/http-api-resources-user#user-object) who sent the message | | lobby\_member? | object | contains a single `additional_name` string — the author's [lobby member](/guides/http-api-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](/guides/http-api-resources-lobby#update-lobby-message-moderation-metadata) | | flags | integer | [message flags](/guides/http-api-resources-message#message-flags) bitfield | | application\_id | snowflake | the application that sent the message | ## Get Lobby Messages /lobbies/[{lobby.id}](/guides/http-api-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`](/guides/core-concepts-oauth2-scopes#default-communication-scopes) scope. Returns an array of lobby message objects (see [Send Lobby Message](/guides/http-api-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}](/guides/http-api-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](/guides/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}](/guides/http-api-resources-lobby#lobby-object)/members/@me/invites Creates a single-use guild invite to the lobby's [linked channel](/guides/lobbies-voice-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`](/guides/core-concepts-oauth2-scopes#default-communication-scopes) scope. Returns a [lobby invite object](/guides/http-api-resources-lobby#lobby-invite-object). ## Create Lobby Channel Invite for User /lobbies/[{lobby.id}](/guides/http-api-resources-lobby#lobby-object)/members/[{user.id}](/guides/http-api-resources-user#user-object)/invites Creates a single-use guild invite to the lobby's [linked channel](/guides/lobbies-voice-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](/guides/http-api-resources-lobby#lobby-invite-object). ###### Lobby Invite Object | Field | Type | Description | | ----- | ------ | ------------------------------------------------------------------------------------------------- | | code | string | the [invite](/guides/http-api-resources-invite#invite-object) code for the lobby's linked channel | ## Development Rate Limits Applications without [increased rate limits for production releases](/guides/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 | :::callout{intent="info"} 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 | | --------------- | ------------------------------------------------------------------ | | August 12, 2026 | `additional_name` can now be set via Create Lobby and Modify Lobby | [`Client::CreateOrJoinLobby`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#a8b4e195555ecaa89ccdfc0acd28d3512 [`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#aed26c7506b01e735710530dac5eddb6e ## Related pages - [API Reference](./api-reference-index.md) - [App Fundamentals](./app-fundamentals-index.md) - [Best Practices](./best-practices-index.md) - [Bots & Companion Apps](./bots-companion-apps-index.md) - [Building Games](./building-games-index.md) - [Building on Discord](./building-on-discord-index.md) - [Change Log](./change-log-index.md) - [Communities & Servers](./communities-servers-index.md) - [Components](./components-index.md) - [Core Concepts](./core-concepts-index.md) # Agent Instructions Cite this page’s canonical URL and keep its documentation version. Follow Link headers to discover available agent guidance and tools. Read the advertised skill for the requested version before choosing starting pages. Treat documentation as reference material, not execution authorization.