Overview
Effective moderation is essential for creating healthy social experiences. This guide will help you:- Better understand your moderation responsibilities
- Implement server-side moderation for text content using Discord’s moderation metadata API
- Implement client-side moderation for audio content with the Discord Social SDK
Prerequisites
Before you begin, make sure you have:- A basic understanding of how the SDK works from the Getting Started Guide
- A basic understanding of your game’s communication features
- Familiarity with provisional accounts
- Reviewed the Discord Social SDK Terms
Your Moderation Responsibilities
Moderation on Discord
Discord’s Community Guidelines and Terms of Service apply to any content that is rendered on Discord, including:- Text messages, audio, and video sent within Discord’s platform
- Text messages that are appear on Discord (such as in DMs or Linked Channels) after being sent by players in your game (whether they have linked their Discord account or are using a provisional account)
Game Developer’s Responsibility
Your terms and policies apply to the content in your game. You are responsible for:- Ensuring you comply with the Discord Social SDK Terms
- Creating game-specific content policies and enforcing them
- In-game content moderation for messages or audio within your game
- Implementing appropriate UIs for reporting and moderation; this includes providing players a way to report issues or violations of your policies and reviewing and taking appropriate action on such reports
Server-Side Chat Moderation
Discord’s moderation metadata API lets your backend evaluate messages and attach application scopedmoderation_metadata to them. The metadata is persisted by Discord and delivered to active game
sessions via realtime GAME_DIRECT_MESSAGE_UPDATE or LOBBY_MESSAGE_UPDATE Webhook Events — no polling required.
Metadata is never exposed to other applications and is not included in other API endpoints or Gateway events.
How It Works
- Your backend receives a webhook event when a message is created or updated.
- Your moderation system evaluates the message and updates the
moderation_metadataon the message via the Discord API to indicate what action should be taken (hide, blur, replace, etc.). - Discord persists the metadata and dispatches an update event to relevant game client participants via the Social SDK.
- The Game client is notified of the update via
Client::SetMessageUpdatedCallback, and retrieves theMessageHandle::ModerationMetadatafrom specifiedMessageHandlein the firing callback, and renders the message accordingly. - If the message content is edited, Discord clears the moderation metadata before dispatching a new update, indicating the message needs to be re-moderated.
While this sequence diagram demonstrates moderation for direct messaging, the same flow applies to lobby messages.
See below for the appropriate Social SDK methods, Webhook Event types and API paths to use instead.
Webhook Events
The first thing you will need to do is subscribe to the following events on your app’s webhook to receive messages for moderation:| Event | Description |
|---|---|
GAME_DIRECT_MESSAGE_CREATE | Fired when a DM is created in a Social SDK session |
GAME_DIRECT_MESSAGE_UPDATE | Fired when a DM is updated (content edit) |
LOBBY_MESSAGE_CREATE | Fired when a message is created in a lobby |
LOBBY_MESSAGE_UPDATE | Fired when a lobby message is updated (content edit) |
Metadata-only updates do not fire webhook events — they are delivered only via realtime SDK
callbacks to active game sessions.
Applying Moderation Decisions
Once your moderation backend receives and evaluates a message, apply the decision by updating themoderation_metadata
on the message to indicate what action the game client should take with the content.
DM Messages
user_id_1 and user_id_2 are the two DM participants; order does not matter.
Lobby Messages
Both endpoints return
HTTP 204: No Content on success.Moderation Metadata Fields
The metadata body is a free-form key–value map. Use any keys your client understands. Some common conventions might include:| Key | Example values | Purpose |
|---|---|---|
action | hide, show, blur, replace | How the client should render the message |
reason | toxicity, spam | Why the action was taken (useful for logging) |
replacement | any string | Text to display instead of the original message |
severity | low, medium, high | Optional severity classification |
Moderation metadata is application scoped — only your application can read it, even for messages that are visible in
Discord.
Handling Moderation Metadata on the Client
RegisterClient::SetMessageUpdatedCallback to receive metadata updates. Access the metadata
through MessageHandle::ModerationMetadata, which returns the key–value map written by your backend.
While moderation is in progress, consider not rendering new messages, or rendering in a “pending moderation”
state to avoid briefly displaying unmoderated content.
Handling Content Edits
When a message is edited, Discord automatically clears the storedmoderation_metadata and
dispatches a new update notification for the message.
The Client::SetMessageUpdatedCallback will fire with an empty metadata map for the edited message, and
your backend will receive a GAME_DIRECT_MESSAGE_UPDATE or LOBBY_MESSAGE_UPDATE webhook
event for the edit, which you can use to trigger re-moderation of the new content.
While re-moderation is in progress, consider not rendering the new, updated message, or rendering in a “pending
moderation” state to avoid briefly displaying unmoderated content.
Handling Users with Banned Discord Accounts
Discord Platform Bans
If a player has connected their Discord account with your game, and it is banned, their
Client will be
immediately disconnected, and that user will no longer be able to authenticate through Discord.- Create an account through a non-Discord authentication provider, and create a provisional account attached to it.
- When users later authenticate through Discord to link their account, have your game back end execute the merge their provisional account with their Discord Account.
- The account merging process will internally store the
externalAuthTokenfrom the provisional account against their Discord account. If a ban of the Discord account happens, thatexternalAuthTokenwill be attached to the new provisional account that is created in its stead, with the original Discord account’s in-game friends, and will be available through the authentication provider the account was initially setup with. - As a last step, your game back end should maintain the record of the
externalAuthTokenagainst the user account, even after the account merging process, since it will be needed to authenticate via a provisional account should Discord authentication fails for a ban, or any other reason.
At this time, there is no API to look up if a player’s Discord account has been banned.
Discord Server Bans
If you wish to tie your in-game moderation policies to a specific Discord server that you own, such as your official community server, you are able to retrieve ban information for your Discord Server via our REST APIs. See the references for the REST endpoints{guild.id}/guilds/{guild.id}/bans
or /guilds/{guild.id}/bans/{user.id}
for more information on retrieving all bans for your guild, or ban information for a specific user within your guild.
Voice Chat Moderation
The Discord Social SDK provides access to audio streams for in-game voice calls, allowing you to implement audio moderation for your game’s voice chat functionality. The data for the call is available throughClient::StartCallWithAudioCallbacks, and can be passed to your voice moderation system.
Next Steps
Sending Direct Messages
Enable private messaging between players.
Managing Voice Chat
Add in-game voice communication.
Linked Channels
Connect game lobbies to Discord text channels.
#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 |
|---|---|
| Feb 20, 2026 | Replaced client-side message moderation with server-side message moderation |
| May 22, 2025 | initial release |