---
sidebar_label: Managing Lobbies
---
import RateLimitCallout from '../partials/callouts/rate-limit.mdx';
import SupportCallout from '../partials/callouts/support.mdx';
import CommsScopeWarning from '../partials/callouts/oauth-comms-scopes.mdx';

[Home](/docs/intro) > [Discord Social SDK](/docs/discord-social-sdk/overview) > [Development Guides](/docs/discord-social-sdk/development-guides) > {sidebar_label}

# Creating and Managing Lobbies

<RateLimitCallout />

## Overview

Lobbies are groups of users that can communicate via text and voice. 

This guide will show you how to:

- Create and manage lobbies
- Handle lobby membership
- Send messages to lobbies

### Prerequisites

Before you begin, make sure you have:

- Set up the Discord Social SDK with our [Getting Started guide](/docs/discord-social-sdk/getting-started)

<CommsScopeWarning />

---

## Lobby Features

Lobbies are groups of users that can communicate with each other via text and voice. Users can be in multiple lobbies at once. A lobby can also have metadata (an arbitrary JSON blob) associated with the lobby and each user.

### Lobby Members

Lobbies may have a maximum of 1,000 members, and each user may have a maximum of 100 lobbies per game. If your game needs more than 1,000 members in a lobby, please get in touch with us to discuss your use case.

### Text Chat

Lobbies have a text chat channel that all members can use to communicate. Messages are sent to all members of the lobby.

### Voice Chat

Lobbies support voice calls. Although a lobby is allowed to have 1,000 members, you should not start voice calls in lobbies that large. 

We recommend sticking to around 25 members or fewer for voice calls, but please do contact Developer Support if you need more than 25 member calls so we can discuss your use case.

---

## Managing Lobbies

There are two ways to manage lobbies:

1. From your server using the Discord API.
2. From the client using the [`Client::CreateOrJoinLobby`] function.

### Server-Side Lobby Management

You can use the Discord HTTP API to create, update, and delete lobbies and manage lobby membership. 

See the [Lobby](/docs/resources/lobby) API resource for available endpoints and [Use with Discord APIs](/docs/discord-social-sdk/how-to/use-with-discord-apis) for information on how to authenticate your requests.

:::info
Clients will not be able to use [`Client::CreateOrJoinLobby`] or [`Client::LeaveLobby`] with lobbies created using the API.
:::

### Client-Side Lobby Management

The SDK client can also create and join lobbies. This works by associating a secret value with the lobby. You can distribute this secret as necessary to folks, and they can then join the lobby using that secret. If the lobby does not exist, it will be created on demand. 

- The relevant SDK functions are [`Client::CreateOrJoinLobby`] and [`Client::LeaveLobby`].   
- Lobby secrets are unique per game (ie: application). For example, use a new secret if you want to generate a new lobby at the end of the match. Calling [`Client::LeaveLobby`] and then [`Client::CreateOrJoinLobby`] with the same secret value will just re-add you to the same lobby.  
- Calling [`Client::CreateOrJoinLobby`] while the user is already in the lobby will update their metadata (if included) instead.  
- Discord's Rich Presence system supports syncing this secret, too.  Using this flow, clients can request to join another user's activity. When approved, the SDK will be given the secret, which you can access and join the associated lobby if you choose to do so. See the [Game Invites for Lobbies](/docs/discord-social-sdk/development-guides/managing-lobbies#creating-lobby-invites) example below.
- If you want to keep track of metadata for the lobby or the lobby members, you can use the [`Client::CreateOrJoinLobbyWithMetadata`] function. This function takes a JSON object as an argument, which will be stored with the lobby and the lobby members. This metadata can be retrieved using the discordpp::Client::GetLobbyHandle function.

```cpp
// Create or join a lobby from the client
client->CreateOrJoinLobby("your-unique-lobby-secret",[client](discordpp::ClientResult result, uint64_t lobbyId) {
  if(result.Successful()) {
    std::cout << "🎮 Lobby created or joined successfully! Lobby Id: " << lobbyId << std::endl;
  } else {
    std::cerr << "❌ Lobby creation/join failed\n";
  }
});
```

#### Leaving a Lobby

To remove a user from a lobby, use the [`Client::LeaveLobby`] function. Only lobbies created with [`Client::CreateOrJoinLobby`] can be left using [`Client::LeaveLobby`].

```cpp
uint64_t lobbyId = 01234567890;

// Leaving a lobby from the client
client->LeaveLobby(lobbyId, [&](discordpp::ClientResult result) {
  if(result.Successful()) {
    std::cout << "🎮 Left lobby successfully! Lobby Id: " << lobbyId << std::endl;
  } else {
    std::cerr << "❌ Leaving lobby failed\n";
  }
}
```

### Lobby Lifecycle

Lobbies are intended to be ephemeral and should be cleaned up when the game/match/area/world is no longer needed. To support this, you can set a "max idle time". This means that if a lobby sits idle, with no one connected to it at all, for more than that time, we will automatically delete the lobby. But as long as one person is connected, the lobby won't be deleted (and the timer resets too).

This value defaults to 5 minutes, and we expect that for most use cases, that will be ok. But we understand there are use cases such as "world chat" that might want to exist longer. The maximum value for this "idle time" will likely be 7 days, so that would mean that the lobby only gets deleted if no one connects to it for an entire week. This should give a good amount of permanence to lobbies when needed, but there may be rare cases where a lobby does need to be "rebuilt" if everyone is offline for an extended period.

:::info
Lobbies created by the SDK client using the [`Client::CreateOrJoinLobby`] function currently have an additional limitation. The "secret" value used in this call expires after 30 days, so the lobby will still exist, but new users won't be able to join the lobby after that.
:::

---

## Sending Messages to a Lobby

Once you have a lobby created, lobby members can send messages to it using the [`Client::SendLobbyMessage`] function.

Clients can send messages to lobbies they are members of regardless of whether they joined the lobby using the client or server-side method.

```cpp
uint64_t lobbyId = 01234567890;

client->SendLobbyMessage(lobbyId, "Hello", [](discordpp::ClientResult result, uint64_t messageId) {
  if(result.Successful()) {
    std::cout << "📨 Message sent successfully!\n";
  } else {
    std::cerr << "❌ Message sending failed\n";
  }
});
```

---

## Receiving Lobby Messages

You can receive messages sent to a lobby using the [`Client::SetMessageCreatedCallback`] function.

This callback will fire whenever a new message is received in a lobby or a DM. From the `messageId`, you can fetch the [`MessageHandle`] and then the [`ChannelHandle`] to determine the location to which the message was sent.

```cpp
client->SetMessageCreatedCallback([&client](uint64_t messageId) {
  discordpp::MessageHandle message = client->GetMessageHandle(messageId);
  std::cout << "📨 New message received: " << message->Content() << "\n";
});
```

---
## Getting Lobby Chat History

You can retrieve previous messages from a lobby using the [`Client::GetLobbyMessagesWithLimit`] function. This allows you to fetch chat history for display when users join a lobby or need to see previous conversations.

The function takes a lobby ID and a limit parameter to specify how many recent messages to retrieve.

**Important limitations:**
- Only a maximum of 200 messages and up to 72 hours of history can be retrieved
- Only messages from lobbies the user is currently a member of can be retrieved

```cpp
const uint64_t lobbyId = 01234567890;
const uint32_t messageLimit = 50; // Number of recent messages to retrieve (max 200)

client->GetLobbyMessagesWithLimit(
  lobbyId, messageLimit,
  [](const discordpp::ClientResult &result, const std::vector<discordpp::MessageHandle> &messages) {
    if (result.Successful()) {
      std::cout << "? Retrieved " << messages.size()
                << " messages from lobby chat history!\n";

      // Process the messages (they are returned in chronological order)
      for (const auto &message : messages) {
        std::cout << "Message: " << message.Content() << std::endl;
      }
    } else {
      std::cerr << "? Failed to retrieve lobby chat history\n";
    }
  });
```

The messages are returned as a list of [`MessageHandle`] objects, ordered chronologically from oldest to newest.
Each [`MessageHandle`] contains the message content, author information, and timestamp.

This is particularly useful for:
- Displaying recent chat when a user joins a lobby
- Implementing chat history scrollback features
- Preserving conversation context across game sessions

---

## Linking a Channel to Lobby

You can connect a lobby to a Discord text channel with Linked Channels. Linked Channels allows users to chat with each other in the lobby using Discord, even if they are not in the game.

See our guide on [Linked Channels](/docs/discord-social-sdk/development-guides/linked-channels) for more information on how to link a channel to a lobby.

---

## Managing Voice Chat

See our guide on [Managing Voice Chat](/docs/discord-social-sdk/development-guides/managing-voice-chat) for more information on how to start a voice call in a lobby.

--- 

## Creating Lobby Invites

Your game can use lobbies and game invites to allow users to invite friends to join an existing lobby.

Check out the [Using Game Invites with Lobbies](/docs/discord-social-sdk/development-guides/managing-game-invites#using-game-invites-with-lobbies) example to try it out in your game.

---

## Next Steps

With your game able to create and manage lobbies, you can now implement additional features:

<Container>
<Card title="Managing Game Invites" link="/docs/discord-social-sdk/development-guides/managing-game-invites" icon="InboxIcon">
    Allow players to invite friends to join their game session or party.
  </Card>
  <Card title="Managing Voice Chat" link="/docs/discord-social-sdk/development-guides/managing-voice-chat" icon="VoiceNormalIcon">
    Add voice communication to your lobbies.
  </Card>
  <Card title="Linked Channels" link="/docs/discord-social-sdk/development-guides/linked-channels" icon="TextControllerIcon">
    Connect lobbies to Discord text channels.
  </Card>
</Container>

<SupportCallout />

---

## Change Log

| Date           | Changes                          |
|----------------|----------------------------------|
| June 30, 2025  | Add communications scope warning |
| March 17, 2025 | initial release                  |

{/* Autogenerated Reference Links */}
[`ChannelHandle`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1ChannelHandle.html#ac32096b2ef15c5c220e9b7b92253cc46
[`Client::CreateOrJoinLobby`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#a8b4e195555ecaa89ccdfc0acd28d3512
[`Client::CreateOrJoinLobbyWithMetadata`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#a5c84fa76c73cf3c0bfd68794ca5595c1
[`Client::GetLobbyMessagesWithLimit`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#a0586192e85caf548b8b321f1cb21301f
[`Client::LeaveLobby`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#a8c78f797240b35d721383461a2e62926
[`Client::SendLobbyMessage`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#a779e0483f51dc99f0db3dd761d22ab6f
[`Client::SetMessageCreatedCallback`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#a28325a8e8c688a84ac851da4bc86e148
[`MessageHandle`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1MessageHandle.html#ae25595b43bc74b0c4c92c5165d16382f