Skip to main content
This guide will walk you through integrating and managing content moderation for your game when using the Discord Social SDK.

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:

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)
Discord can take various actions against such content on Discord for violating its terms or policies, including through Discord platform-wide account bans and restrictions. Actions against a player’s Discord account will not affect their separate account in the game (see below for more details); however, if a player’s Discord account is banned, they will no longer have access to the SDK features that require an account connection.

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
As a reminder, you are responsible for any third-party moderation toolkits or services you use for your game and will ensure you comply with any applicable terms and laws, including obtaining consents from players as necessary for processing their data using such moderation services.

Server-Side Chat Moderation

Discord’s moderation metadata API lets your backend evaluate messages and attach application scoped moderation_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

  1. Your backend receives a webhook event when a message is created or updated.
  2. Your moderation system evaluates the message and updates the moderation_metadata on the message via the Discord API to indicate what action should be taken (hide, blur, replace, etc.).
  3. Discord persists the metadata and dispatches an update event to relevant game client participants via the Social SDK.
  4. The Game client is notified of the update via Client::SetMessageUpdatedCallback, and retrieves the MessageHandle::ModerationMetadata from specified MessageHandle in the firing callback, and renders the message accordingly.
  5. 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:
EventDescription
GAME_DIRECT_MESSAGE_CREATEFired when a DM is created in a Social SDK session
GAME_DIRECT_MESSAGE_UPDATEFired when a DM is updated (content edit)
LOBBY_MESSAGE_CREATEFired when a message is created in a lobby
LOBBY_MESSAGE_UPDATEFired when a lobby message is updated (content edit)
See the Webhook Events reference for full event schemas.
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 the moderation_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.
import requests

API_ENDPOINT = 'https://discord.com/api/v10'
BOT_TOKEN = 'YOUR_BOT_TOKEN'

def apply_dm_moderation(user_id_1, user_id_2, message_id, metadata):
  r = requests.put(
    f'{API_ENDPOINT}/partner-sdk/dms/{user_id_1}/{user_id_2}/messages/{message_id}/moderation-metadata',
    headers={
      'Authorization': f'Bot {BOT_TOKEN}',
      'Content-Type': 'application/json',
    },
    json=metadata
  )
  r.raise_for_status()

# Instruct the client to hide this message — moderation service flagged it as toxic
metadata = {
  'action': 'hide',   # client will not render this message
  'reason': 'toxicity',  # logged by the client for reporting purposes
}
apply_dm_moderation(user_id_1, user_id_2, message_id, metadata)

# Alternatively, instruct the client to show this message — moderation service approved it
metadata = {
  'action': 'show',  # client will render the message normally
}
apply_dm_moderation(user_id_1, user_id_2, message_id, metadata)

Lobby Messages

import requests

API_ENDPOINT = 'https://discord.com/api/v10'
BOT_TOKEN = 'YOUR_BOT_TOKEN'

def apply_lobby_moderation(lobby_id, message_id, metadata):
  r = requests.put(
    f'{API_ENDPOINT}/lobbies/{lobby_id}/messages/{message_id}/moderation-metadata',
    headers={
      'Authorization': f'Bot {BOT_TOKEN}',
      'Content-Type': 'application/json',
    },
    json=metadata
  )
  r.raise_for_status()

# Instruct the client to replace the message content with a policy reminder
metadata = {
  'action': 'replace',  # client will display replacement text instead of the original
  'replacement': 'Be kind to others!',  # the text the client will render in place of the message
}
apply_lobby_moderation(lobby_id, message_id, metadata)
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:
KeyExample valuesPurpose
actionhide, show, blur, replaceHow the client should render the message
reasontoxicity, spamWhy the action was taken (useful for logging)
replacementany stringText to display instead of the original message
severitylow, medium, highOptional severity classification
Limits: Up to 5 keys per message; key length ≤ 1024 characters; value length ≤ 2000 characters (the maximum Discord message length, so values can contain modified message content).
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

Register Client::SetMessageUpdatedCallback to receive metadata updates. Access the metadata through MessageHandle::ModerationMetadata, which returns the key–value map written by your backend.
client->SetMessageUpdatedCallback([&client](uint64_t messageId) {
    if (auto message = client->GetMessageHandle(messageId)) {
        auto metadata = message->ModerationMetadata();
        if (metadata.empty()) {
            // No moderation decision yet — render as pending, normally, or hide completely,
            // depending on your moderation requirements
            renderPendingModeration(message);
            return;
        }
        auto action = metadata.count("action") ? metadata.at("action") : "show";
        if (action == "hide") {
            hideMessage(messageId);
        } else if (action == "show") {
            renderMessage(message);
        } else if (action == "replace") {
            renderMessage(messageId, metadata.at("replacement"));
        } else if (action == "blur") {
            renderBlurred(message);
        } else {
            std::cerr << "Unknown moderation action: " << action << "\n";
            renderMessage(message);  // fall back to rendering normally
        }
    }
});
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 stored moderation_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.
The recommended path for integrating the Discord Social SDK is that your game has a primary authentication other than Discord that initially sets up a provisional account, and have the player link their Discord account to this primary authentication. This approach protects your users’ game access and data if they encounter issues with their Discord account, such as a permanent or temporary ban. To implement this recommended path:
  1. Create an account through a non-Discord authentication provider, and create a provisional account attached to it.
  2. 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.
  3. The account merging process will internally store the externalAuthToken from the provisional account against their Discord account. If a ban of the Discord account happens, that externalAuthToken will 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.
  4. As a last step, your game back end should maintain the record of the externalAuthToken against 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.
If you use Discord as the primary or sole authentication mechanism for your game, you risk players permanently losing access to their in-game data if their Discord account is banned, as there is no way to migrate them to a provisional account that is connected to an external authentication provider.
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 through Client::StartCallWithAudioCallbacks, and can be passed to your voice moderation system.
// Example: Capturing local voice chat audio for asynchronous moderation.

// Callback for local users' audio with moderation
auto capturedCallback = [](int16_t const* data,
                     uint64_t samplesPerChannel, int32_t sampleRate,
                     uint64_t channels) {
    // Call the moderation function
    moderateCapturedVoice(data, samplesPerChannel);
};

// Start the call with our moderation callback
auto call = client->StartCallWithAudioCallbacks(lobbyId, receivedCallback, capturedCallback);

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

DateChanges
Feb 20, 2026Replaced client-side message moderation with server-side message moderation
May 22, 2025initial release