Connected Accounts

Connections are links between third party accounts to Discord accounts.

Connection Object

The connection object that the user has attached.

Connection Structure

Field	Type	Description
id	string	ID of the connection account
type	string	The type of the connection
name	string	The username of the connection account
verified	boolean	Whether the connection is verified
metadata?	object	Service-specific metadata about the connection
metadata_visibility	integer	Visibility of the connection's metadata
revoked	boolean	whether the connection is revoked
integrations ¹ ²	array[connection integration object]	The guild integrations attached to the connection
friend_sync	boolean	Whether friend sync is enabled for this connection
show_activity	boolean	Whether activities related to this connection will be shown in presence
two_way_link	boolean	Whether this connection has a corresponding third party OAuth2 token
visibility	integer	Visibility of the connection
access_token? ¹	string	The access token for the connection account

¹ Not included when fetching a user's connections via OAuth2.

² These integrations can be used to join your own sub-enabled guild or the guild of a creator you are supporting.

Partial Connection Structure

Field	Type	Description
id	string	ID of the connection account
type	string	The type of the connection
name	string	The username of the connection account
verified	boolean	Whether the connection is verified
metadata?	object	Service-specific metadata about the connection

Example Connection

{
  "type": "reddit",
  "id": "run&hide",
  "name": "alien",
  "visibility": 1,
  "friend_sync": false,
  "show_activity": true,
  "verified": true,
  "two_way_link": false,
  "metadata_visibility": 1,
  "metadata": {
    "gold": "0",
    "mod": "1",
    "total_karma": "20223",
    "created_at": "2019-05-02T20:28:37"
  },
  "revoked": false,
  "integrations": []
}

Example Partial Connection

{
  "type": "reddit",
  "id": "run&hide",
  "name": "alien",
  "verified": true,
  "metadata": {
    "gold": "0",
    "mod": "1",
    "total_karma": "20223",
    "created_at": "2019-05-02T20:28:37"
  }
}

Connection Integration Structure

Field	Type	Description
id ¹	snowflake	The ID of the integration
type	string	The type of integration
account	account object	The integration's account information
guild	integration guild object	The guild that the integration is attached to

¹ This field may also be the literal string "twitch-partners" to represent the Twitch Partners integration.

Example Connection Integration

{
  "id": "twitch-partners",
  "type": "twitch",
  "account": {
    "id": "92473777",
    "name": "discordapp"
  },
  "guild": {
    "id": "107939014299901952",
    "name": "Twitch Partners",
    "icon": "62450d21b75478191962d9c4b81831ae"
  }
}

Connection Type

Value	Name
amazon-music	Amazon Music
battlenet	Battle.net
bluesky	Bluesky
bungie	Bungie.net
contacts ²	Contact Sync
crunchyroll	Crunchyroll
domain	Domain
ebay	eBay
epicgames	Epic Games
facebook	Facebook
github	GitHub
instagram ¹	Instagram
leagueoflegends	League of Legends
mastodon	Mastodon
paypal	PayPal
playstation	PlayStation Network
playstation-stg	PlayStation Network (Staging)
reddit	Reddit
roblox	Roblox
riotgames	Riot Games
samsung ¹	Samsung Galaxy
soundcloud	SoundCloud
spotify	Spotify
skype ¹	Skype
steam	Steam
tiktok	TikTok
twitch	Twitch
twitter	Twitter
xbox	Xbox
youtube	YouTube

¹ Service can no longer be added by users.

² Service is not returned in Get User Profile or when fetching a user's connections via OAuth2.

Visibility Type

Value	Name	Description
0	NONE	Invisible to everyone except the user themselves
1	EVERYONE	Visible to everyone

Partial connections always have a visibility of 1.

Console Device Object

Console Device Structure

Field	Type	Description
id	snowflake	The ID of the device
name	string	The name of the device
platform	string	The console platform (only `playstation` and `playstation-stg` are allowed)

Example Console Device

{
  "id": "1371598138300956672",
  "name": "My Gifted PlayStation 5",
  "platform": "playstation"
}

Endpoints

Authorize User Connection

GET/connections/{connection.type}/authorize

Returns an authorization link that can be used for authorizing a new connection.

Query String Params

Field	Type	Description
two_way_link_type?	?string	The type of two-way link to create
two_way_user_code?	?string	The device code to use for the two-way link
continuation?	boolean	Whether this is a continuation of a previous authorization

Two Way Link Type

Value	Description
web	The connection is linked via web
mobile	The connection is linked via mobile
desktop	The connection is linked via desktop

Response Body

Field	Type	Description
url	string	The authorization link for the user

Create User Connection Callback

POST/connections/{connection.type}/callback

Creates a new connection for the current user. Returns a connection object on success. Fires a User Connections Update Gateway event.

JSON Params

Field	Type	Description
code	string	The authorization code for the connection
state	string	The state used to authorize the connection
two_way_link_code?	string	The code to use for two-way linking
insecure?	boolean	Whether the connection is insecure (default false)
friend_sync?	boolean	Whether to sync friends over the connection
openid_params?	object	Additional parameters for OpenID Connect

Create Contact Sync Connection

PUT/users/@me/connections/contacts/{connection.id}

Creates a new contact sync connection for the current user. Returns a connection object on success. Fires a User Connections Update Gateway event.

JSON Params

Field	Type	Description
name	string	The username of the connection account
friend_sync?	boolean	Whether to sync friends over the connection

Update External Friend List Entries

PUT/users/@me/connections/contacts/{connection.id}/external-friend-list-entries

Syncs the user's device contacts to the connection. May fire multiple Friend Suggestion Create Gateway events.

JSON Params

Field	Type	Description
friend_list_entries	array[friend list entry object]	The phone numbers to sync (max 10000)
background	boolean	Whether the request is a background sync (will not return suggestions)
allowed_in_suggestions	integer	The contact sync suggestions setting
include_mutual_friends_count	boolean	Whether to show the mutual friend count of contacts
add_reverse_friend_suggestions?	boolean	Whether to add users that have contact synced the current user as friend suggestions

Friend List Entry Structure

Field	Type	Description
friend_id	string	E.164-formatted phone number of the contact

Contact Sync Suggestions Setting

Value	Name	Description
1	MUTUAL_CONTACT_INFO_ONLY	Users who have contact synced that have the current user as a contact
2	ANYONE_WITH_CONTACT_INFO	Users who have contact synced

Response Body

Field	Type	Description
bulk_add_token	?string	Token to be used for bulk adding relationships
friend_suggestions	array[friend suggestion object]	Suggested users

Contact Sync Settings

GET/users/@me/connections/contacts/{connection.id}/external-friend-list-entries/settings

Response Body

Field	Type	Description
allowed_in_suggestions	integer	The contact sync suggestions setting

Create Domain Connection

POST/users/@me/connections/domain/{connection.id}

Creates a new domain connection for the current user. Returns a connection object on success. Fires a User Connections Update Gateway event.

When attempting to create a domain connection, Discord will verify that the domain is owned by the user. If this verification fails, the endpoint will return an error response:

{ "message": "Unable to validate domain.", "code": 50187, "proof": "dh=dceaca792e3c40fcf356a9297949940af5cfe538" }

The proof provided must be added to the domain's DNS records as a TXT record with the name _discord.<domain>. Alternatively, the proof can be served at https://<domain>/.well-known/discord.

After adding the proof, the request should be retried.

Get User Connections

GET/users/@me/connections

Returns a list of connection objects.

Get User Connection Access Token

GET/users/@me/connections/{connection.type}/{connection.id}/access-token

Returns a new access token for the given connection. Only available for Twitch, YouTube, and Spotify connections. Fires a User Connections Update Gateway event.

Response Body

Field	Type	Description
access_token	string	The connection's access token

Get User Connection Subreddits

GET/users/@me/connections/reddit/{connection.id}/subreddits

Returns a list of subreddits the connected account moderates. Only available for Reddit connections.

Subreddit Structure

Field	Type	Description
id	string	The subreddit's ID
subscribers	integer	The number of joined Reddit users
url	string	The subreddit's relative URL

Example Response

[
  {
    "id": "t5_388p4",
    "subscribers": 1044184,
    "url": "/r/discordapp/"
  }
]

Refresh User Connection

POST/users/@me/connections/{connection.type}/{connection.id}/refresh

Refreshes a connection. Returns a 204 empty response on success. Fires a User Connections Update Gateway event.

Modify User Connection

PATCH/users/@me/connections/{connection.type}/{connection.id}

Modifies a connection. Returns a connection object on success. Fires a User Connections Update Gateway event.

Not all connection types support all parameters.

JSON Params

Field	Type	Description
name	string	The connection's username
show_activity	boolean	Whether activities related to this connection will be shown in presence
friend_sync	boolean	Whether friend sync is enabled for this connection
metadata_visibility	integer	Visibility of the connection's metadata
visibility	integer	Visibility of the connection

Field	Type	Description
analytics_properties?	connect request properties object	The properties used for analytics

Connect Request Properties Structure

Field	Type	Description
handoff_type	string	The console handoff type

Console Handoff Type

Value	Description
CREATE_NEW_CALL	Create a new call on a console device
TRANSFER_EXISTING_CALL	Transfer an existing call to a console device

Response Body

Field	Type	Description
nonce	string	The nonce

Example Response

{ "nonce": "fgnmC0tT" }

Field	Type	Description
devices	array[console device object]	The user console devices

Send Console Command

POST/consoles/{connection.type}/devices/{device.id}/commands

Sends a command to connect to a voice call on a console device.

JSON Params

Field	Type	Description
command	string	The command type
channel_id	snowflake	The ID of the channel to connect to
guild_id?	snowflake	The ID of the guild the channel is in
nonce?	string	The nonce obtained from Create Console Connection endpoint

Console Command Type

Value	Description
connect_voice	Connect to a voice call

Response Body

Field	Type	Description
id	snowflake	The ID of the sent command

Cancel Console Command

DELETE/consoles/{connection.type}/devices/{device.id}/commands/{command.id}

Cancels a console command. Returns a 204 empty response on success.