Managing Relationships in Your Game

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

Before you begin, make sure you have:

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

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.

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.

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

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

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:

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

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

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

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

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

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

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

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

Continue learning about the Discord Social SDK with these guides:

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