Creating and Managing Lobbies

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

Before you begin, make sure you have:

• Set up the Discord Social SDK with our Getting Started guide

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.

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.

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

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.

There are two ways to manage lobbies:

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

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

See the Lobby API resource for available endpoints and Use with Discord APIs for information on how to authenticate your requests.

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

// 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";
  }
});

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

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";
  }
}

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.

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.

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";
  }
});

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.

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

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

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

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 for more information on how to link a channel to a lobby.

The first time a user sends a message in a lobby that's linked to a Discord channel, the SDK will inject a disclosure message into the chat that contains a basic English explanation that their messages are now visible on Discord. This message is private to the sending user and does not appear in the lobby's message history—other lobby members will not see it.

You can identify these messages with the MessageHandle::DisclosureType method.

We encourage you to customize the rendering of these messages, possibly changing the wording, translating them, and making them look aligned with the style and aesthetic of your game. You can choose to avoid rendering these as well.

This does not apply to lobbies that aren't linked to a Discord channel.

See our guide on Managing Voice Chat for more information on how to start a voice call in a lobby.

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 example to try it out in your game.

Applications without increased rate limits for production releases are subject to the following application-wide limits:

These limitations are designed to provide sufficient capacity for development, testing, and small-scale demos while ensuring system stability.

For guidance on detecting and retrying rate limited requests in the SDK, see Handle Rate Limits.

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

Need help? Join the Discord Developers Server and share questions in the #social-sdk-dev-help channel for support from the community.

If you encounter a bug while working with the Social SDK, please report it here: https://dis.gd/social-sdk-bug-report