> ## Documentation Index
> Fetch the complete documentation index at: https://discord-markm-docs-lobby-membership-disconnect.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Lobby Resource

> Reference for Discord lobby objects used for matchmaking.

export const Route = ({method, children}) => {
  return <div className="MDXRoute">
      <span className={"verb" + " " + method.toLowerCase()}>{method}</span>
      <span className="url">{children}</span>
    </div>;
};

export const ManualAnchor = ({id}) => {
  return <div className="MDXManualAnchor" id={id}></div>;
};

### Lobby Object

Represents a lobby within Discord. See [Managing Lobbies](/developers/discord-social-sdk/development-guides/managing-lobbies) for more information.

<ManualAnchor id="lobby-object-lobby-structure" />

###### 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](/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.

<ManualAnchor id="lobby-member-object-lobby-member-structure" />

###### 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](/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`] |

<ManualAnchor id="lobby-member-object-lobby-member-flags" />

###### Lobby Member Flags

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

<ManualAnchor id="lobby-member-object-example-lobby-object" />

###### Example Lobby Object

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

## Create Lobby

<Route method="POST">/lobbies</Route>

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

Returns a [lobby](/developers/resources/lobby#lobby-object) object.

<Info>
  [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.
</Info>

### 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](/developers/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\<string, string> | 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

<Route method="PUT">/lobbies</Route>

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\<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

<Route method="GET">/lobbies/[\{lobby.id}](/developers/resources/lobby#lobby-object)</Route>

Returns a [lobby](/developers/resources/lobby#lobby-object) object for the specified lobby id, if it exists.

## Modify Lobby

<Route method="PATCH">/lobbies/[\{lobby.id}](/developers/resources/lobby#lobby-object)</Route>

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\<string, string> | 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. |
| 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

<Route method="DELETE">/lobbies/[\{lobby.id}](/developers/resources/lobby#lobby-object)</Route>

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

<Route method="PUT">/lobbies/[\{lobby.id}](/developers/resources/lobby#lobby-object)/members/[\{user.id}](/developers/resources/user#user-object)</Route>

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\<string, string> | 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

<Route method="POST">/lobbies/[\{lobby.id}](/developers/resources/lobby#lobby-object)/members/bulk</Route>

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.

<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.
</Info>

### 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](/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

<Route method="DELETE">/lobbies/[\{lobby.id}](/developers/resources/lobby#lobby-object)/members/[\{user.id}](/developers/resources/user#user-object)</Route>

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

<Route method="DELETE">/lobbies/[\{lobby.id}](/developers/resources/lobby#lobby-object)/members/@me</Route>

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

<Route method="PATCH">/lobbies/[\{lobby.id}](/developers/resources/lobby#lobby-object)/channel-linking</Route>

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

<Route method="PATCH">/lobbies/[\{lobby.id}](/developers/resources/lobby#lobby-object)/channel-linking</Route>

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

<Route method="POST">/lobbies/[\{lobby.id}](/developers/resources/lobby#lobby-object)/messages</Route>

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.

<Info>
  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.
</Info>

### 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](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\<string, string> | dispatch-only metadata sent with the message |
| moderation\_metadata? | ?dict\<string, string> | 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

<Route method="GET">/lobbies/[\{lobby.id}](/developers/resources/lobby#lobby-object)/messages</Route>

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

<Route method="PUT">/lobbies/[\{lobby.id}](/developers/resources/lobby#lobby-object)/messages/\{message.id}/moderation-metadata</Route>

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

<Route method="POST">/lobbies/[\{lobby.id}](/developers/resources/lobby#lobby-object)/members/@me/invites</Route>

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

<Route method="POST">/lobbies/[\{lobby.id}](/developers/resources/lobby#lobby-object)/members/[\{user.id}](/developers/resources/user#user-object)/invites</Route>

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).

<ManualAnchor id="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 |

<Info>
  These are per-application rate limits, not per-user.
</Info>

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