Relationships

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

Field	Type	Description
id	string	The ID of the target user
type	integer	The type of relationship
user	partial user	The target user
nickname	?string	The nickname of the user in this relationship (1-32 characters)
is_spam_request?	boolean	Whether the friend request was flagged as spam (default false)
stranger_request?	boolean	Whether the friend request was sent by a user without a mutual friend or small mutual guild (default false)
user_ignored	boolean	Whether the target user has been ignored by the current user
origin_application_id?	?snowflake	The ID of the application that created the relationship
since?	ISO8601 timestamp	When the user requested a relationship
has_played_game? ¹	boolean	Whether the target user has authorized the same application the current user's session is associated with

¹ Only available in OAuth2 contexts.

Relationship Type

Value	Name	Description
0	NONE	No relationship exists
1	FRIEND	The user is a friend
2	BLOCKED	The user is blocked
3	INCOMING_REQUEST	The user has sent a friend request to the current user
4	OUTGOING_REQUEST	The current user has sent a friend request to the user
5	IMPLICIT	The user is an affinity of the current user
6	~~SUGGESTION~~	~~The 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

Field	Type	Description
id	string	The ID of the target user
application_id	snowflake	The ID of the application whose game the relationship originated from
type	integer	The type of relationship
user ¹	partial user	The target user
since	ISO8601 timestamp	When the user requested a relationship
dm_access_type	integer	The DM access level for the relationship
user_id	snowflake	The ID of the current user

¹ Not included when fetching game relationships via OAuth2.

Game Relationship Type

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

DM Access Type

The values of this enum are currently unknown. Help us by figuring them out and submitting a pull request!

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

Field	Type	Description
suggested_user	partial user object	The suggested user
reasons	array[friend suggestion reason object]	The sources of the suggestion
from_suggested_user_contacts?	boolean	Whether the suggested user has the current user in their contacts

Friend Suggestion Reason Structure

Field	Type	Description
type	integer	The type of reason
platform	string	The platform that the suggestion originated from
name	string	The user's name on the platform

Friend Suggestion Reason Type

Value	Name	Description
1	EXTERNAL_FRIEND	The 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

Returns a list of relationship objects for the current user.

Send Friend Request

POST/users/@me/relationships

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

Field	Type	Description
username	string	The username of the user to send a friend request to
discriminator ¹	?string	The discriminator of the user to send a friend request to

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

Create Relationship

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

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

JSON Params

Field	Type	Description
type?	integer	The relationship type to create (defaults to -1, which accepts an existing or creates a new friend request)
from_friend_suggestion?	boolean	Whether the relationship was created from a friend suggestion (default false)
confirm_stranger_request?	boolean	Whether the user consents to accepting a stranger's friend request (default false)

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

Field	Type	Description
nickname? ¹	string	The nickname of the user in this relationship (1-32 characters)

¹ Only applicable to relationships of type FRIEND.

Remove Relationship

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

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

Field	Type	Description
relationship_type?	integer	Remove relationships with this relationship type (default `INCOMING_REQUEST`, only `INCOMING_REQUEST` is allowed)
only_spam? (deprecated)	boolean	Whether to remove relationships that were flagged as spam (default false)

JSON Params

Field	Type	Description
filters?	array[integer]	The relationship removal filters to match against, using AND logic

Relationship Removal Filter

Value	Name	Description
1	SPAM	Friend requests flagged by Discord as spam
2	IGNORED	Ignored users

Bulk Add Relationships

POST/users/@me/relationships/bulk

Adds multiple relationships from contact sync. May fire multiple Relationship Add Gateway events.

JSON Params

Field	Type	Description
user_ids	array[snowflake]	IDs of users to add
token	string	The contact sync bulk add token

Response Body

Field	Type	Description
failed_requests	array[snowflake]	IDs of the users who could not be friend requested
successful_requests	array[snowflake]	IDs of the users who were friend requested

Get Game Relationships

GET/users/@me/game-relationships

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

Send Game Friend Request

POST/users/@me/game-relationships

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

Field	Type	Description
username	string	The username of the user to send a game friend request to

Create Game Relationship

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

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

Field	Type	Description
type?	integer	The 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.

Field	Type	Description
type?	integer	The relationship type to create (only `FRIEND` is allowed)