discord · markmandel · Jun 30, 2025 · Jun 27, 2025 · Jun 30, 2025
@@ -88,6 +88,76 @@ The Discord Social SDK is available for the following platforms:
 
 ---
 
+## OAuth2 Scopes
+
+OAuth2 scopes define the level of access your app has to a user's Discord account
+
+What OAuth scopes are available to your integration are set via
+[`AuthorizationArgs::SetScopes`] on [`AuthorizationArgs`] which is passed to [`Client::Authorize`] on Social SDK
+authentication.
+
+### Default Presence Scopes
+
+At a minimum, the Social SDK uses the following scopes to use features like rich presence and friends list:
+
+- `openid`
+- `sdk.social_layer_presence`
+
+The default presence features include:
+
+* [Account Linking](/docs/discord-social-sdk/core-concepts#account-linking)
+* [Provisional Accounts](/docs/discord-social-sdk/core-concepts#provisional-accounts)
+* [Friend System & Relationships](/docs/discord-social-sdk/core-concepts#friend-system-relationships)
+* [Presence & Rich Presence](/docs/discord-social-sdk/core-concepts#presence-rich-presence)
+
+The Social SDK provides the helper method [`Client::GetDefaultPresenceScopes`], which returns `openid sdk.social_layer_presence`,
+that you can use when setting up your OAuth2 flow, for integrations that only need the above functionality.
+
+:::warn
+With only the default presence scopes, your game will not be able to use any of the limited access
+communications features.
+:::
+
+### Default Communication Scopes
+
+The communications features are currently available but have limited access. Those features **require** the scope
+of `sdk.social_layer`, which includes the `sdk.social_layer_presence` scope but also allows your app to use those limited features on behalf of the user.
+
+- `openid`
+- `sdk.social_layer`
+
+These communication features include:
+* [Messaging & Communication](/docs/discord-social-sdk/core-concepts#messaging-communication)
+* [Lobbies & In-Game Chat](/docs/discord-social-sdk/core-concepts#lobbies-ingame-chat)
+* [Linked Channels](/docs/discord-social-sdk/core-concepts#linked-channels)
+
+The Social SDK provides the helper method [`Client::GetDefaultCommunicationScopes`], which returns `openid sdk.social_layer`,
+that you can use when setting up your OAuth2 flow, for integrations that integrates both the default and limited communications features.
+
+:::preview
+For more information about these features, please see [Core Concepts: Limited Access Features](/docs/discord-social-sdk/core-concepts#limited-access-features).
+:::
+
+If your game requires additional scopes, you can add them to the default scopes to authorize additional access from your users.
+
+You should only add scopes that are necessary for your game to function. Requesting unnecessary scopes can lead to user distrust and may result in users not linking their Discord account.
+
+See [available OAuth2 scopes](/docs/topics/oauth2#shared-resources-oauth2-scopes) available with the Discord API.
+
+### OAuth2 Client Types
+
+OAuth2 has two client types: **Public** and **Confidential**. Most games will not want to ship with **Public Client** enabled.
+
+Some Social SDK methods require your Discord application to be a **Public Client**. These methods also have server-side alternatives that you can use with a **Confidential Client**.
+
+- Public clients cannot securely store client secrets.
+- Using confidential clients with proper secret management for production applications is generally recommended.
+- Your security team should review this setting and authentication flows before releasing your game.
+
+[Learn more about OAuth2 client types](https://oauth.net/2/client-types)
+
+---
+
 ## Core Features
 
 The Discord Social SDK offers a range of features to enhance social interactions within games. Developers can leverage these features to create a more engaging and connected experience for players in their game.
@@ -138,8 +208,8 @@ The SDK models friendships and relationships in two ways:
 
 Users can communicate via direct messages (DMs) and voice calls:
 
-- DMs: One-on-one private chat (`MessageHandle`).
-- Calls: Real-time voice communication inside a game lobby (`Call`).  
+- DMs: One-on-one private chat ([`MessageHandle`]).
+- Calls: Real-time voice communication inside a game lobby ([`Call`]).
 
 | Development Guides                                                                             |
 |------------------------------------------------------------------------------------------------|
@@ -200,47 +270,6 @@ Games can link in-game chat with Discord's server-based text channels in their U
 - Respect user privacy: Never send friend requests or messages without user consent.
 - Design intuitive UI/UX: Ensure social features blend seamlessly with the gameplay.
 
-### OAuth2 Scopes
-
-OAuth2 scopes define the level of access your app has to a user's Discord account. 
-
-At a minimum, the Social SDK uses the following scopes to use features like rich presence and friends list:
-
-- `openid`
-- `sdk.social_layer_presence`
-
-Some SDK features are currently available but have limited access. Those features require the following scope of `sdk.social_layer`, which includes the `sdk.social_layer_presence` scope but also allows your app to use those limited features on behalf of the user.
-
-- `openid`
-- `sdk.social_layer`
-
-:::preview
-For more information about these features, please see [Core Concepts: Limited Access Features](/docs/discord-social-sdk/core-concepts#limited-access-features).
-:::
-
-The Social SDK provides two helper methods that you can use when setting up your OAuth2 flow:
-
-- [`Client::GetDefaultPresenceScopes`], which returns "openid sdk.social_layer_presence".
-- [`Client::GetDefaultCommunicationScopes`], which returns "openid sdk.social_layer".
-
-If your game requires additional scopes, you can add them to the default scopes to authorize additional access from your users.
-
-You should only add scopes that are necessary for your game to function. Requesting unnecessary scopes can lead to user distrust and may result in users not linking their Discord account.
-
-See [available OAuth2 scopes](/docs/topics/oauth2#shared-resources-oauth2-scopes) available with the Discord API.
-
-### OAuth2 Client Types
-
-OAuth2 has two client types: **Public** and **Confidential**. Most games will not want to ship with **Public Client** enabled.
-
-Some Social SDK methods require your Discord application to be a **Public Client**. These methods also have server-side alternatives that you can use with a **Confidential Client**.
-
-- Public clients cannot securely store client secrets.
-- Using confidential clients with proper secret management for production applications is generally recommended.
-- Your security team should review this setting and authentication flows before releasing your game.
-
-[Learn more about OAuth2 client types](https://oauth.net/2/client-types)
-
 ### Design Guidelines
 
 Check out the [Discord Social SDK Design Guidelines](/docs/discord-social-sdk/design-guidelines) for more best practices and common integration scenarios.
@@ -265,13 +294,18 @@ Learn more about [Using the Discord HTTP API](/docs/discord-social-sdk/developme
 
 ## Change Log
 
-| Date           | Changes         |
-|----------------|-----------------|
-| March 17, 2025 | initial release |
+| Date           | Changes                  |
+|----------------|--------------------------|
+| June 30, 2025  | restructure oauth scopes |
+| March 17, 2025 | initial release          |
 
 {/* Autogenerated Reference Links */}
+[`AuthorizationArgs`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1AuthorizationArgs.html#adb47ac55258db29d4cb8a2c506093eed
+[`AuthorizationArgs::SetScopes`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1AuthorizationArgs.html#aa3714d11a196e0d71c8c1cf38c506d92
+[`Call`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Call.html#a1cc8a7f73c15a960bc409d734b5edbd1
 [`Client`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#a91716140c699d8ef0bdf6bfd7ee0ae13
 [`Client::Authorize`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#ace94a58e27545a933d79db32b387a468
 [`Client::GetDefaultCommunicationScopes`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#a71499da752fbdc2d4326ae0fd36c0dd1
 [`Client::GetDefaultPresenceScopes`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#a7648bd1d2f7d9a86ebd0edb8bef12b5c
-[`Client::GetProvisionalToken`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#a8003130b6c46e54ac68442483bf0480c
+[`Client::GetProvisionalToken`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#a8003130b6c46e54ac68442483bf0480c
+[`MessageHandle`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1MessageHandle.html#ae25595b43bc74b0c4c92c5165d16382f
@@ -2,8 +2,8 @@
 sidebar_label: Linked Channels
 ---
 import LimitedAccessCallout from '../partials/callouts/limited-access.mdx';
-import PublicClient from '../partials/callouts/public-client.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}
 
@@ -27,6 +27,8 @@ Before implementing Linked Channels, make sure you have:
 - [Set up the Discord Social SDK](/docs/discord-social-sdk/getting-started)
 - An understanding of [Creating and Managing Lobbies](/docs/discord-social-sdk/development-guides/managing-lobbies)
 
+<CommsScopeWarning />
+
 ---
 
 ## Linked Channel Requirements
@@ -313,9 +315,10 @@ int main() {
 
 ## Change Log
 
-| Date           | Changes         |
-|----------------|-----------------|
-| March 17, 2025 | initial release |
+| Date           | Changes                          |
+|----------------|----------------------------------|
+| June 30, 2025  | Add communications scope warning |
+| March 17, 2025 | initial release                  |
 
 {/* Autogenerated Reference Links */}
 [`Client::GetGuildChannels`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#adba1e5a83c219a9c4f6dab1657778017

@@ -2,8 +2,8 @@
 sidebar_label: Managing Lobbies
 ---
 import LimitedAccessCallout from '../partials/callouts/limited-access.mdx';
-import PublicClient from '../partials/callouts/public-client.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}
 
@@ -27,6 +27,8 @@ 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
@@ -195,9 +197,10 @@ With your game able to create and manage lobbies, you can now implement addition
 
 ## Change Log
 
-| Date           | Changes         |
-|----------------|-----------------|
-| March 17, 2025 | initial release |
+| 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

@@ -2,8 +2,8 @@
 sidebar_label: Managing Voice Chat
 ---
 import LimitedAccessCallout from '../partials/callouts/limited-access.mdx';
-import PublicClient from '../partials/callouts/public-client.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}
 
@@ -27,7 +27,9 @@ This guide will show you how to:
 
 Before you can start a voice call, you must complete these essential steps:
 
-### 1. Lobby Management (Required)
+<CommsScopeWarning />
+
+### 1. Lobby Management
 
 **Voice calls require an active lobby with participants.** You must:
 
@@ -295,10 +297,11 @@ This information is particularly useful for:
 
 ## Change Log
 
-| Date           | Changes         |
-|----------------|-----------------|
-| March 17, 2025 | initial release |
-| June 19, 2025  | released guide  |
+| Date           | Changes                          |
+|----------------|----------------------------------|
+| June 30, 2025  | Add communications scope warning |
+| June 19, 2025  | released guide                   |
+| March 17, 2025 | initial release                  |
 
 {/* Autogenerated Reference Links */}
 [`Call`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Call.html#a1cc8a7f73c15a960bc409d734b5edbd1

@@ -2,8 +2,8 @@
 sidebar_label: Sending Direct Messages
 ---
 import LimitedAccessCallout from '../partials/callouts/limited-access.mdx';
-import PublicClient from '../partials/callouts/public-client.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}
 
@@ -18,6 +18,14 @@ Direct Messages (DMs) allow players to communicate privately. This guide will sh
 - Send text messages between users
 - Handle displaying messages in your game
 
+### 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 />
+
 ### Types of Chat Messages
 
 The Discord Social SDK SDK supports two types of chat:
@@ -143,10 +151,11 @@ Now that you know how to send and receive messages, check out these other Discor
 
 ## Change Log
 
-| Date           | Changes             |
-|----------------|---------------------|
-| May 06, 2025   | link to DM Settings |
-| March 17, 2025 | initial release     |
+| Date           | Changes                          |
+|----------------|----------------------------------|
+| June 30, 2025  | Add communications scope warning |
+| May 06, 2025   | link to DM Settings              |
+| March 17, 2025 | initial release                  |
 
 {/* Autogenerated Reference Links */}
 [`ChannelHandle`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1ChannelHandle.html#ac32096b2ef15c5c220e9b7b92253cc46

@@ -0,0 +1,7 @@
+:::warn
+To utilize this communication feature, you must enable [`Client::GetDefaultCommunicationScopes`] in your OAuth Scope configuration.
+See the [OAuth Scopes Core Concepts Guide](/docs/discord-social-sdk/core-concepts#oauth2-scopes) for more details.
+:::
+
+{/* Autogenerated Reference Links */}
+[`Client::GetDefaultCommunicationScopes`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#a71499da752fbdc2d4326ae0fd36c0dd1