Relationships Resource

Relationships in Discord are used to represent friendships, pending friend requests, and blocked users. Game relationships are used to distinguish special bonds created while in-game.

Relationship Object

A relationship between the current user and another user.

Relationship Structure
FieldTypeDescription
idstringThe ID of the target user
typeintegerThe type of relationship
userpartial userThe target user
nickname?stringThe nickname of the user in this relationship (1-32 characters)
is_spam_request?booleanWhether the friend request was flagged as spam (default false)
stranger_request?booleanWhether the friend request was sent by a user without a mutual friend or small mutual guild (default false)
user_ignoredbooleanWhether the target user has been ignored by the current user
origin_application_id??snowflakeThe ID of the application that created the relationship
since?ISO8601 timestampWhen the user requested a relationship
Relationship Type
ValueNameDescription
0NONENo relationship exists
1FRIENDThe user is a friend
2BLOCKEDThe user is blocked
3INCOMING_REQUESTThe user has sent a friend request to the current user
4OUTGOING_REQUESTThe current user has sent a friend request to the user
5IMPLICITThe user is an affinity of the current user
6SUGGESTIONThe user is a friend suggestion for the current user
Example Relationship
{
  "id": "852892297661906993",
  "type": 3,
  "nickname": null,
  "user_ignored": false,
  "user": {
    "id": "852892297661906993",
    "username": "alien",
    "global_name": "Alien",
    "avatar": "14733482e560d9267c0a414b21b2fb8d",
    "discriminator": "0",
    "public_flags": 64,
    "avatar_decoration_data": null,
    "primary_guild": null
  },
  "is_spam_request": false,
  "since": "2023-02-10T01:58:05.348000+00:00",
  "stranger_request": false
}

Game Relationship Object

An in-game relationship between the current user and another user, created using the social layer SDK.

Game Relationship Structure
FieldTypeDescription
idstringThe ID of the target user
application_idsnowflakeThe ID of the application whose game the relationship originated from
typeintegerThe type of relationship
userpartial userThe target user
sinceISO8601 timestampWhen the user requested a relationship
dm_access_typeintegerThe DM access level for the relationship
user_idsnowflakeThe ID of the current user
Game Relationship Type

This enum is a subset of the relationship type enum, supporting only FRIEND, INCOMING_REQUEST, and OUTGOING_REQUEST.

DM Access Type

This enum is unknown.

Example Game Relationship
{
  "user_id": "852892297661906993",
  "application_id": "1237856342484717650",
  "id": "1001086404203389018",
  "type": 1,
  "since": "2025-01-22T00:26:18.616000+00:00",
  "dm_access_type": 0,
  "user": {
    "id": "1001086404203389018",
    "username": ".dziurwa",
    "global_name": "Dziurwa💕",
    "avatar": "f6c0363fbab45668fcf8f88fea56db9c",
    "avatar_decoration_data": null,
    "discriminator": "0",
    "public_flags": 4210944,
    "primary_guild": null
  }
}

Friend Suggestion Object

A friend suggestion for the current user.

Friend Suggestion Structure
FieldTypeDescription
suggested_userpartial user objectThe suggested user
reasonsarray[friend suggestion reason object]The sources of the suggestion
from_suggested_user_contacts?booleanWhether the suggested user has the current user in their contacts
Friend Suggestion Reason Structure
FieldTypeDescription
typeintegerThe type of reason
platformstringThe platform that the suggestion originated from
namestringThe user's name on the platform
Friend Suggestion Reason Type
ValueNameDescription
1EXTERNAL_FRIENDThe user is a friend on another platform
Example Friend Suggestion
{
  "suggested_user": {
    "id": "852892297661906993",
    "username": "alien",
    "global_name": "Alien",
    "avatar": "14733482e560d9267c0a414b21b2fb8d",
    "discriminator": "0",
    "public_flags": 64,
    "avatar_decoration_data": null,
    "primary_guild": null
  },
  "reasons": [
    {
      "type": 1,
      "platform_type": "contacts",
      "name": "Gnarpy"
    }
  ]
}

Endpoints

Get Relationships

GET/users/@me/relationships
OAuth2

Returns a list of relationship objects for the current user.

Query String Params
FieldTypeDescription
with_implicit? 1booleanWhether to include implicit relationships (default false)

1 Only usable with OAuth2 requests. On non-OAuth2 requests, only user-created relationships will be returned.

Send Friend Request

POST/users/@me/relationships
OAuth2

Sends a friend request to another user, which can be accepted by creating a new relationship of type FRIEND. Returns a 204 empty response on success. Fires a Relationship Add Gateway event.

JSON Params
FieldTypeDescription
usernamestringThe username of the user to send a friend request to
discriminator 1?stringThe discriminator of the user to send a friend request to, if not migrated

1 null for migrated users. See the section on Discord's new username system for more information.

Create Relationship

PUT/users/@me/relationships/{user.id}
OAuth2

Creates a relationship with another user. Returns a 204 empty response on success. Fires a Relationship Add Gateway event.

JSON Params
FieldTypeDescription
type?integerThe relationship type to create (defaults to -1, which accepts an existing or creates a new friend request)
from_friend_suggestion?booleanWhether the relationship was created from a friend suggestion (default false)
friend_token? 1stringThe friend token of the user to add as a friend

1 Providing a valid friend token will bypass the user's friend request settings.

Ignore User

PUT/users/@me/relationships/{user.id}/ignore

Ignores a user. Returns a 204 empty response on success. Fires a Relationship Add or Relationship Update Gateway event.

Unignore User

DELETE/users/@me/relationships/{user.id}/ignore

Unignores a user. Returns a 204 empty response on success. Fires a Relationship Update or Relationship Remove Gateway event.

Modify Relationship

PATCH/users/@me/relationships/{user.id}

Modifies a relationship to another user. Returns a 204 empty response on success. Fires a Relationship Update Gateway event.

JSON Params
FieldTypeDescription
nickname? 1stringThe nickname of the user in this relationship (1-32 characters)

1 Only applicable to relationships of type FRIEND.

Remove Relationship

DELETE/users/@me/relationships/{user.id}
OAuth2

Removes a relationship with another user. Returns a 204 empty response on success. Fires a Relationship Remove Gateway event.

Bulk Remove Relationships

DELETE/users/@me/relationships

Removes multiple relationships. Returns a 204 empty response on success. May fire multiple Relationship Remove Gateway events.

Query Params
FieldTypeDescription
relationship_type?integerRemove relationships with this relationship type (default INCOMING_REQUEST, only INCOMING_REQUEST is allowed)
only_spam?booleanWhether to remove relationships that were flagged as spam (default false)

Get Game Relationships

GET/users/@me/game-relationships
OAuth2

Returns a list of game relationship objects for the current user.

Send Game Friend Request

POST/users/@me/game-relationships
OAuth2

Sends a game friend request to another user, which can be accepted in-game by creating a new game relationship of type FRIEND, or by the user independently. Returns a 204 empty response on success. Fires a Game Relationship Add Gateway event.

JSON Params
FieldTypeDescription
usernamestringThe username of the user to send a game friend request to

Create Game Relationship

PUT/users/@me/game-relationships/{user.id}
OAuth2

Creates a game relationship with another user. Returns a 204 empty response on success. Fires a Game Relationship Add Gateway event.

FieldTypeDescription
type?integerThe relationship type to create (defaults to -1, which accepts an existing or creates a new friend request)

Create Game Relationship by Application

PUT/users/@me/game-relationships/{user.id}/{application.id}

Accepts a game relationship from another user on a specific application. Returns a 204 empty response on success. Fires a Game Relationship Add Gateway event.

FieldTypeDescription
type?integerThe relationship type to create (only FRIEND is allowed)

Remove Game Relationship

DELETE/users/@me/game-relationships/{user.id}
OAuth2

Removes a game relationship with another user. Returns a 204 empty response on success. Fires a Game Relationship Remove Gateway event.

Remove Game Relationship by Application

DELETE/users/@me/game-relationships/{user.id}/{application.id}

Removes a game relationship with another user. Returns a 204 empty response on success. Fires a Game Relationship Remove Gateway event.

Get Friend Suggestions

GET/friend-suggestions

Returns a list of friend suggestion objects for the current user.

Remove Friend Suggestion

DELETE/friend-suggestions/{user.id}

Removes a friend suggestion for the current user. Returns a 204 empty response on success. Fires a Friend Suggestion Delete Gateway event.