Managing Relationships in Your Game

Overview

The Discord Social SDK lets you manage relationships between players in your game. This guide will show you how to:

Send and accept friend requests
Handle different types of relationships
Block and unblock users
Work with both Discord-wide and game-specific friendships

Prerequisites

Before you begin, make sure you have:

Completed the Getting Started guide
Completed the Creating a Unified Friends List guide

This feature requires the Default Presence Scopes (openid and sdk.social_layer_presence). Use Client::GetDefaultPresenceScopes when configuring your OAuth2 flow. See the OAuth2 Scopes guide for details on all available scopes.

Understanding Relationship Types

Discord models the relationship between two users using the Relationship entity in the SDK. Relationships are not just for friends. They are also used to send and receive friend requests and block other users.

While the SDK allows you to manage a user’s relationships, you should never act without their explicit consent. You should not automatically send or accept friend requests. Only invoke APIs to manage relationships in response to a user action such as clicking a “Send Friend Request” button.

Relationship Types

We know that sometimes users will want to be friends with each other across all their games. If they start playing a new game, they can see all of their previous friends and don’t start from scratch. But sometimes, they don’t want to give out that access and only want to be friends in the current game they are playing. To support this, the Discord Social SDK supports two types of relationships between users:

Discord relationships: These relationships persist across games and on the Discord client. Both users can see whether each other is online, regardless of whether they are in the same game. Discord Relationships are the same as becoming a friend in the Discord client.
Game relationships: These are per-game relationships and do not carry over to other games. The two users can only see if the other is online if they are playing a game in which they are friends. Game friends can DM each other, and those DMs will show up in Discord, but they can disable that behavior and keep their game conversations restricted to just the game. That option is located in the “Content & Social” User settings, under the “Connected Games” tab at the top of the page.

RelationshipHandle can be used to determine the type of friendship between the player and another user. It has two fields:

RelationshipHandle::DiscordRelationshipType for the Discord friendship
RelationshipHandle::GameRelationshipType for the game friendship

Having both of these friend types is important because a pair of users might start out as game friends but later choose to “upgrade” to being full Discord friends. In this case, their RelationshipHandle::DiscordRelationshipType would be set to RelationshipType::PendingIncoming or RelationshipType::PendingOutgoing (based on whether they are receiving or sending the request respectively), and their RelationshipHandle::GameRelationshipType would remain as RelationshipType::Friend. While our API technically supports users being both types of friends, you don’t have to ensure that every Discord friend is a game friend or vice versa. When adding friends, offer users a choice of friend type and explain the difference. See our design guidelines for more.

Discord Friend Relationships

Persist across all games and Discord
Limited to 1,000 friends
Online status visible everywhere
Full Discord chat functionality

Game Friend Relationships

Only exist within your game
No current friend limit
Online status is only visible in-game

Relationship Actions

Once you’ve created a unified friends list, you can start managing relationships between players in your game. Here are some common actions you might want to take:

Sending Game Friend Requests

Sends (or accepts) a game friend request to the target user. You can send game friend requests to users using their Discord unique username or user ID. After the friend request is sent, each user will have a new game relationship created. For the current user, the RelationshipHandle::GameRelationshipType will be RelationshipType::PendingOutgoing, and for the target user, it will be RelationshipType::PendingIncoming. If the current user has already received a game friend request from the target user (meaning RelationshipHandle::GameRelationshipType is RelationshipType::PendingIncoming), the two users will become game friends. The request fails if the target user has blocked the current user. The callback receives an error code 80001, and ClientResult::Error set to Friend request blocked.

client->SendGameFriendRequest("username", [](discordpp::ClientResult result) {
  if (result.Successful()) {
    std::cout << "🎮 Game friend request sent successfully!\n";
  }
});

client->SendGameFriendRequestById(123456789, [](discordpp::ClientResult result) {
  if (result.Successful()) {
    std::cout << "🎮 Game friend request sent successfully!\n";
  }
});

Sending Discord Friend Requests

Sends (or accepts) a Discord friend request to the target user. You can send Discord friend requests to users by using their Discord unique username or user ID. After the friend request is sent, each user will have a new Discord relationship created. For the current user, the RelationshipHandle::DiscordRelationshipType will be RelationshipType::PendingOutgoing, and for the target user, it will be RelationshipType::PendingIncoming. If the current user has already received a Discord friend request from the target user (meaning RelationshipHandle::DiscordRelationshipType is RelationshipType::PendingIncoming), the two users will become Discord friends. Like game friend requests, the request fails with error code 80001 if the target user has blocked the current user.

client->SendDiscordFriendRequest("username", [](discordpp::ClientResult result) {
  if (result.Successful()) {
    std::cout << "🎮 Discord friend request sent successfully!\n";
  }
});

client->SendDiscordFriendRequestById(123456789, [](discordpp::ClientResult result) {
  if (result.Successful()) {
    std::cout << "🎮 Discord friend request sent successfully!\n";
  }
});

Accept Incoming Friend Requests

Allow your players to accept incoming friend requests, which RelationshipType::PendingIncoming represents.

// RelationshipHandle::DiscordRelationshipType == RelationshipType::PendingIncoming
client->AcceptDiscordFriendRequest(userId, [](discordpp::ClientResult result) {
  if (result.Successful()) {
    std::cout << "🎮 Discord friend request accepted!\n";
  }
});

// RelationshipHandle::GameRelationshipType == RelationshipType::PendingIncoming
client->AcceptGameFriendRequest(userId, [](discordpp::ClientResult result) {
  if (result.Successful()) {
    std::cout << "🎮 Game friend request accepted!\n";
  }
});

Reject Incoming Friend Requests

Allow your players to reject incoming friend requests, which RelationshipType::PendingIncoming represents.

// Reject Incoming Friend Requests
// RelationshipHandle::DiscordRelationshipType == RelationshipType::PendingIncoming
client->RejectDiscordFriendRequest(userId,[](discordpp::ClientResult result) {
  if (result.Successful()) {
    std::cout << "🎮 Discord friend request rejected!\n";
  }
});

// RelationshipHandle::GameRelationshipType == RelationshipType::PendingIncoming
client->RejectGameFriendRequest(userId, [](discordpp::ClientResult result) {
  if (result.Successful()) {
    std::cout << "🎮 Game friend request rejected!\n";
  }
});

Cancel Outgoing Friend Requests

Allow your players to cancel outgoing friend requests, which RelationshipType::PendingOutgoing represents.

// Cancel Outgoing Friend Requests
// RelationshipHandle::DiscordRelationshipType == RelationshipType::PendingIncoming
client->CancelDiscordFriendRequest(userId, [](discordpp::ClientResult result) {
  if (result.Successful()) {
    std::cout << "🎮 Discord friend request canceled!\n";
  }
});

// RelationshipHandle::GameRelationshipType == RelationshipType::PendingOutgoing
client->CancelGameFriendRequest(userId, [](discordpp::ClientResult result) {
  if (result.Successful()) {
    std::cout << "🎮 Game friend request canceled!\n";
  }
});

Managing Existing Relationships

Allow your players to remove existing relationships with other users. This will remove the relationship from both users, and they will no longer be able to see each other’s online status or send messages.

// Removes any friendship between the current user and the target user. 
// This function will remove BOTH any Discord friendship and any game friendship between the users.
client->RemoveDiscordAndGameFriend(userId, [](discordpp::ClientResult result) {
  if (result.Successful()) {
    std::cout << "🎮 Discord and Game friendships removed!\n";
  }
});

// Removes any game friendship between the current user and the target user.
client->RemoveGameFriend(userId, [](discordpp::ClientResult result) {
  if (result.Successful()) {
    std::cout << "🎮 Game friendship removed!\n";
  }
});

Blocking Users

Allow your players to block another user so they cannot send friend or activity invites and cannot message them anymore. Blocks are always Discord-wide. A block is stored on RelationshipHandle::DiscordRelationshipType as RelationshipType::Blocked and never on RelationshipHandle::GameRelationshipType, so check the Discord relationship type to detect a block regardless of whether the two users were game friends. It is not possible to block a user in only one game. When a player blocks another user:

Any existing Discord friendship between the two users is removed.
Any game friendship between the two users is removed in every game where they were game friends, not only the game the block was made from.
Any pending friend requests between them are cancelled, in both directions, for both Discord and game friendships.
The blocked user can no longer send the player friend requests of either type.

Blocking works the same way whether or not either user is a provisional account.

client->BlockUser(userId, [](discordpp::ClientResult result) {
  if (result.Successful()) {
    std::cout << "🎮 User blocked successfully!\n";
  }
});

Blocking a user does not mute them in lobby voice calls. See Voice Muting Based on Player Blocks to drive voice muting from block relationships.

Unblocking Users

Allow your players to unblock another user if they have been blocked. Unblocking a user does not restore any previous relationships between the users, including game friendships that the block removed. Client::UnblockUser fails if the target user is not currently blocked. Gate the unblock action on RelationshipHandle::DiscordRelationshipType being RelationshipType::Blocked rather than offering it unconditionally.

client->UnblockUser(userId, [](discordpp::ClientResult result) {
  if (result.Successful()) {
    std::cout << "🎮 User unblocked successfully!\n";
  }
});

Relationship Request Failures

Relationship actions that fail server-side return an ErrorType::HTTPError result. Read ClientResult::ErrorCode to tell these cases apart, and ClientResult::Error for the message. All of the errors below use HTTP status 400, and none of them are retryable.

Code	HTTP Status	Meaning	Solution
30002	400	Maximum number of friends reached	The player is at the Discord friend limit and must remove a friend first
80001	400	Friend request blocked	The target user has blocked the player; do not retry or reveal that they were blocked
80002	400	Bots cannot have friends	The target user is a bot account and cannot be added
80003	400	Cannot send friend request to self	The target user is the current player
80004	400	No users with DiscordTag exist	No user matches the username; only returned by the username-based overloads
80005	400	No incoming friend request	Accept or reject was called with no pending incoming request for that user
80007	400	You are already friends with that user	The two users are already friends of the requested type
80009	400	Users have no common application	Both users must be authorized in the same game before a game friendship can be made
80012	400	Game relationship limit reached	The player is at the per-game friend limit and must remove a game friend first

Errors 80009 and 80012 apply only to game friendships. The rest apply to both game and Discord relationship actions.

Next Steps

Continue learning about the Discord Social SDK with these guides:

Creating a Unified Friends List

Combine Discord and game friends into a single list for easy management.

Managing Game Invites

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

Managing Lobbies

Bring players together in a shared lobby with invites, text chat, and voice comms.

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
March 17, 2025	Initial release
September 9, 2026	Clarify blocking behavior and document relationship errors

Discord Social SDK

Core Concepts

Getting Started

Design Foundations

Provisional Accounts

Discord Account Linking

Friends & Relationships

Rich Presence & User Status

Game Invites

Direct Messages

Lobbies & Voice

Game Stats Widgets

How To

Overview

Prerequisites

Understanding Relationship Types

Relationship Types

Discord Friend Relationships

Game Friend Relationships

Relationship Actions

Sending Game Friend Requests

Sending Discord Friend Requests

Accept Incoming Friend Requests

Reject Incoming Friend Requests

Cancel Outgoing Friend Requests

Managing Existing Relationships

Blocking Users

Unblocking Users

Relationship Request Failures

Next Steps

Creating a Unified Friends List

Managing Game Invites

Managing Lobbies

Change Log

​Overview

​Prerequisites

​Understanding Relationship Types

​Relationship Types

​Discord Friend Relationships

​Game Friend Relationships

​Relationship Actions

​Sending Game Friend Requests

​Sending Discord Friend Requests

​Accept Incoming Friend Requests

​Reject Incoming Friend Requests

​Cancel Outgoing Friend Requests

​Managing Existing Relationships

​Blocking Users

​Unblocking Users

​Relationship Request Failures

​Next Steps

Creating a Unified Friends List

Managing Game Invites

Managing Lobbies

​Change Log

Overview

Prerequisites

Understanding Relationship Types

Relationship Types

Discord Friend Relationships

Game Friend Relationships

Relationship Actions

Sending Game Friend Requests

Sending Discord Friend Requests

Accept Incoming Friend Requests

Reject Incoming Friend Requests

Cancel Outgoing Friend Requests

Managing Existing Relationships

Blocking Users

Unblocking Users

Relationship Request Failures

Next Steps

Change Log