> ## Documentation Index
> Fetch the complete documentation index at: https://discord-anthony-embed-unfurl-components.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Managing Relationships in Your Game

> Manage Discord user relationships including friends and blocked users in your application.

export const InboxIcon = props => <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" fill="none"><path fill="currentColor" fill-rule="evenodd" d="M5 2a3 3 0 0 0-3 3v14a3 3 0 0 0 3 3h14a3 3 0 0 0 3-3V5a3 3 0 0 0-3-3H5ZM4 5.5C4 4.67 4.67 4 5.5 4h13c.83 0 1.5.67 1.5 1.5v6c0 .83-.67 1.5-1.5 1.5h-2.65c-.5 0-.85.5-.85 1a3 3 0 1 1-6 0c0-.5-.35-1-.85-1H5.5A1.5 1.5 0 0 1 4 11.5v-6Z" clip-rule="evenodd" /></svg>;

export const UserIcon = props => <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" fill="none"><path fill="currentColor" d="M12 10a4 4 0 1 0 0-8 4 4 0 0 0 0 8ZM11.53 11A9.53 9.53 0 0 0 2 20.53c0 .81.66 1.47 1.47 1.47h.22c.24 0 .44-.17.5-.4.29-1.12.84-2.17 1.32-2.91.14-.21.43-.1.4.15l-.26 2.61c-.02.3.2.55.5.55h11.7a.5.5 0 0 0 .5-.55l-.27-2.6c-.02-.26.27-.37.41-.16.48.74 1.03 1.8 1.32 2.9.06.24.26.41.5.41h.22c.81 0 1.47-.66 1.47-1.47A9.53 9.53 0 0 0 12.47 11h-.94Z" /></svg>;

export const ListViewIcon = props => <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" fill="none"><path fill="currentColor" d="M4 2a2 2 0 1 0 0 4 2 2 0 0 0 0-4ZM4 10a2 2 0 1 0 0 4 2 2 0 0 0 0-4ZM2 20a2 2 0 1 1 4 0 2 2 0 0 1-4 0ZM9 3a1 1 0 0 0 0 2h12a1 1 0 1 0 0-2H9ZM8 12a1 1 0 0 1 1-1h12a1 1 0 1 1 0 2H9a1 1 0 0 1-1-1ZM9 19a1 1 0 1 0 0 2h12a1 1 0 1 0 0-2H9Z" /></svg>;

## 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](/developers/discord-social-sdk/getting-started) guide
* Completed the [Creating a Unified Friends List](/developers/discord-social-sdk/development-guides/creating-a-unified-friends-list) guide

<Info>
  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](/developers/discord-social-sdk/core-concepts/oauth2-scopes) for details on all available scopes.
</Info>

[`Client::GetDefaultPresenceScopes`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#a7648bd1d2f7d9a86ebd0edb8bef12b5c

***

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

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

### 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](/developers/discord-social-sdk/development-guides/creating-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`.

```cpp theme={"system"}
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.

```cpp theme={"system"}
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.

```cpp theme={"system"}
// 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.

```cpp theme={"system"}
// 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.

```cpp theme={"system"}
// 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.

```cpp theme={"system"}
// 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.

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

<Info>
  Blocking a user does not mute them in lobby voice calls. See [Voice Muting Based on Player Blocks](/developers/discord-social-sdk/how-to/voice-muting-for-blocked-players) to drive voice muting from block relationships.
</Info>

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

```cpp theme={"system"}
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        |

<Info>
  Errors `80009` and `80012` apply only to game friendships. The rest apply to both game and Discord
  relationship actions.
</Info>

***

## Next Steps

Continue learning about the Discord Social SDK with these guides:

<CardGroup cols={3}>
  <Card title="Creating a Unified Friends List" href="/developers/discord-social-sdk/development-guides/creating-a-unified-friends-list" icon={<ListViewIcon />}>
    Combine Discord and game friends into a single list for easy management.
  </Card>

  <Card title="Managing Game Invites" href="/developers/discord-social-sdk/development-guides/managing-game-invites" icon={<InboxIcon />}>
    Allow players to invite friends to join their game session or party.
  </Card>

  <Card title="Managing Lobbies" href="/developers/discord-social-sdk/development-guides/managing-lobbies" icon={<UserIcon />}>
    Bring players together in a shared lobby with invites, text chat, and voice comms.
  </Card>
</CardGroup>

Need help? Join the [Discord Developers Server](https://discord.gg/discord-developers) 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](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 |

[`Client::UnblockUser`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#acd8dc8d7e5c202256a219a65cfedae47

[`ClientResult::Error`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1ClientResult.html#a3175ab59cd9268a3b2c6484129c89e04

[`ClientResult::ErrorCode`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1ClientResult.html#ab361cb3d3381401f0d73736d5f49b3f5

[`RelationshipHandle`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1RelationshipHandle.html#a7da36b15ad0b7d38ba658a622e9ded77

[`RelationshipHandle::DiscordRelationshipType`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1RelationshipHandle.html#a5fecfb79a4a2b6f3dc5f73b09d0c3881

[`RelationshipHandle::GameRelationshipType`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1RelationshipHandle.html#aa60146eb72ede07e3e615565f61f97eb