Friends

Discord models the relationship between two users using the Relationship entity in the SDK. Relationships are not just for friends though, they are also for sending and receiving friend requests, as well as blocking other users.

Note: While the SDK allows you to manage a user's relationships, you should never take an action 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, that way 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.

So, the SDK supports two types of relationships between users:

• Discord relationships: These are relationships that persist across games and on the Discord client. Both users will be able to see whether each other is online regardless of whether they are in the same game or not. This is 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 will only be able to 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 have the option to disable that behavior as well and keep their game conversations restricted to just the game. That option is located at the bottom of the "Content & Social" settings.

discordpp::RelationshipHandle can be used to determine the type of friendship that exists. It has two fields:

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

One reason having both of these friend types is important is because a pair of users might start out as being game friends, but later choose to "upgrade" to being full Discord friends. In this case, their discordpp::RelationshipHandle::DiscordRelationshipType would be set to discordpp::RelationshipType::PendingIncoming or discordpp::RelationshipType::PendingOutgoing (based on whether they are receiving or sending the request respectively), and their discordpp::RelationshipHandle::GameRelationshipType would remain as discordpp::RelationshipType::Friend.

While our API technically supports users being both types of friends, you don't have to ensure that every Discord friend is also 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.

Relationship Actions

Since there are two types of relationships, each relationship action in the SDK has two variants, one for each friend type. For example to send a friend request, you must call either discordpp::Client::SendDiscordFriendRequest or discordpp::Client::SendGameFriendRequest based on which type of friend the user wants to be.

Blocking

discordpp::RelationshipType::Blocked is a special relationship type. When a user blocks another user, it is always stored on the discordpp::RelationshipHandle::DiscordRelationshipType field, and will persist across games. It is not possible to block a user in only one game. Blocking a user will also remove any existing relationship (game or Discord) between the users and cancel any pending requests.

Friend Limits

Users are limited to 1,000 Discord friends. There is currently no limit on game friends but one will be added in the future.

Friends List

Here's a small code snippet that demonstrates all the APIs you may need to use in order to construct a friends list using the Discord SDK. To do that you'll need to query all relationships, and then find out the name and type of each user, what type of friend they are, whether they are online. The example below should print out all of a users friends to your console for debugging:

std::vector<std::string> relationships{};
for (auto& relationship: client.GetRelationships()) {
    auto user = relationship.User();
    if (!user) {
        continue;
    }
 
    std::string str{};
    // Identifying information about the user:
    str += " DiscordName: " + user->DisplayName();
    str += " DiscordId: " + std::to_string(user->Id());
    // Provisional users don't have a Discord icon shown next to them:
    str += " IsProvisional: " + std::to_string(user->IsProvisional());
    // Whether the relationship is for a friend, a friend request, or because the user is blocked:
    // For a friends list you'll want to filter out blocked users
    // And likely display friend requests in a different section
    str += " DiscordRelationshipType: " + std::string(discordpp::EnumToString(relationship.DiscordRelationshipType()));
    str += " GameRelationshipType: " + std::string(discordpp::EnumToString(relationship.GameRelationshipType()));
    // Whether the user is online/offline/etc:
    str += " IsOnlineAnywhere: " + std::to_string(user->Status() != discordpp::StatusType::Offline);
    str += " IsOnlineInGame: " + std::to_string(user->GameActivity() != std::nullopt);
    relationships.push_back(str);
}
 
std::sort(relationships.begin(), relationships.end());
for (auto str : relationships) {
    printf("%s\n", str.c_str());
}