Creating and Managing Lobbies

Create and manage game lobbies with Discord Social SDK for matchmaking.

Creating and Managing Lobbies

:::warn This feature is currently available with rate limits. To remove the rate limits for your game, please follow Communication Features: Applying for Rate Limit Removal. :::

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

To utilize this communication feature, you must enable Client::GetDefaultCommunicationScopes in your OAuth Scope configuration. See the OAuth Scopes Core Concepts Guide for more details.

---

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 API resource for available endpoints and Use with Discord APIs for information on how to authenticate your requests.

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

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.

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.

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.

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.

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

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

---

Managing Voice Chat

See our guide on 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 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:

Managing Game Invites

Allow players to invite friends to join their game session or party.

Managing Voice Chat

Add voice communication to your lobbies.

Linked Channels

Connect lobbies to Discord text channels.

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

---

Change Log

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