diff --git a/docs/resources/Application.md b/docs/resources/Application.md index 780fd8be3a..d9b3213d91 100644 --- a/docs/resources/Application.md +++ b/docs/resources/Application.md @@ -4,29 +4,30 @@ ###### Application Structure -| Field | Type | Description | -| ---------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | -| id | snowflake | the id of the app | -| name | string | the name of the app | -| icon | ?string | the [icon hash](#DOCS_REFERENCE/image-formatting) of the app | -| description | string | the description of the app | -| rpc_origins? | array of strings | an array of rpc origin urls, if rpc is enabled | -| bot_public | boolean | when false only app owner can join the app's bot to guilds | -| bot_require_code_grant | boolean | when true the app's bot will only join upon completion of the full oauth2 code grant flow | -| terms_of_service_url? | string | the url of the app's terms of service | -| privacy_policy_url? | string | the url of the app's privacy policy | -| owner? | partial [user](#DOCS_RESOURCES_USER/user-object) object | partial user object containing info on the owner of the application | -| summary *(deprecated)* | string | **deprecated and will be removed in v11.** An empty string. | -| verify_key | string | the hex encoded key for verification in interactions and the GameSDK's [GetTicket](#DOCS_GAME_SDK_APPLICATIONS/getticket) | -| team | ?[team](#DOCS_TOPICS_TEAMS/data-models-team-object) object | if the application belongs to a team, this will be a list of the members of that team | -| guild_id? | snowflake | if this application is a game sold on Discord, this field will be the guild to which it has been linked | -| primary_sku_id? | snowflake | if this application is a game sold on Discord, this field will be the id of the "Game SKU" that is created, if exists | -| slug? | string | if this application is a game sold on Discord, this field will be the URL slug that links to the store page | -| cover_image? | string | the application's default rich presence invite [cover image hash](#DOCS_REFERENCE/image-formatting) | -| flags? | integer | the application's public [flags](#DOCS_RESOURCES_APPLICATION/application-object-application-flags) | -| tags? | array of strings | up to 5 tags describing the content and functionality of the application | -| install_params? | [install params](#DOCS_RESOURCES_APPLICATION/install-params-object) object | settings for the application's default in-app authorization link, if enabled | -| custom_install_url? | string | the application's default custom authorization link, if enabled | +| Field | Type | Description | +| ---------------------------------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| id | snowflake | the id of the app | +| name | string | the name of the app | +| icon | ?string | the [icon hash](#DOCS_REFERENCE/image-formatting) of the app | +| description | string | the description of the app | +| rpc_origins? | array of strings | an array of rpc origin urls, if rpc is enabled | +| bot_public | boolean | when false only app owner can join the app's bot to guilds | +| bot_require_code_grant | boolean | when true the app's bot will only join upon completion of the full oauth2 code grant flow | +| terms_of_service_url? | string | the url of the app's terms of service | +| privacy_policy_url? | string | the url of the app's privacy policy | +| owner? | partial [user](#DOCS_RESOURCES_USER/user-object) object | partial user object containing info on the owner of the application | +| summary *(deprecated)* | string | **deprecated and will be removed in v11.** An empty string. | +| verify_key | string | the hex encoded key for verification in interactions and the GameSDK's [GetTicket](#DOCS_GAME_SDK_APPLICATIONS/getticket) | +| team | ?[team](#DOCS_TOPICS_TEAMS/data-models-team-object) object | if the application belongs to a team, this will be a list of the members of that team | +| guild_id? | snowflake | if this application is a game sold on Discord, this field will be the guild to which it has been linked | +| primary_sku_id? | snowflake | if this application is a game sold on Discord, this field will be the id of the "Game SKU" that is created, if exists | +| slug? | string | if this application is a game sold on Discord, this field will be the URL slug that links to the store page | +| cover_image? | string | the application's default rich presence invite [cover image hash](#DOCS_REFERENCE/image-formatting) | +| flags? | integer | the application's public [flags](#DOCS_RESOURCES_APPLICATION/application-object-application-flags) | +| tags? | array of strings | up to 5 tags describing the content and functionality of the application | +| install_params? | [install params](#DOCS_RESOURCES_APPLICATION/install-params-object) object | settings for the application's default in-app authorization link, if enabled | +| custom_install_url? | string | the application's default custom authorization link, if enabled | +| role_connections_verification_url? | string | the application's role connection verification entry point, which when configured will render the app as a verification method in the guild role verification configuration | ###### Example Application Object diff --git a/docs/resources/Application_Role_Connection_Metadata.md b/docs/resources/Application_Role_Connection_Metadata.md new file mode 100644 index 0000000000..7dbecdc9a4 --- /dev/null +++ b/docs/resources/Application_Role_Connection_Metadata.md @@ -0,0 +1,49 @@ +# Application Role Connection Metadata + +A representation of role connection metadata for an [application](#DOCS_RESOURCES_APPLICATION/). + +When a guild has added a bot and that bot has configured its [`role_connections_verification_url`](#DOCS_RESOURCES_APPLICATION/application-object) (in the developer portal), the application will render as a potential verification method in the guild's role verification configuration. + +If an application has configured role connection metadata, its metadata will appear in the role verification configuration when the application has been added as a verification method to the role. + +When a user connects their account using the bot's [`role_connections_verification_url`](#DOCS_RESOURCES_APPLICATION/application-object), the bot will [update a user's role connection with metadata](#DOCS_RESOURCES_USER/update-user-application-role-connection) using the OAuth2 `role_connections.write` scope. + +### Application Role Connection Metadata Object + +###### Application Role Connection Metadata Structure + +| Field | Type | Description | +| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | +| type | [ApplicationRoleConnectionMetadataType](#DOCS_RESOURCES_APPLICATION_ROLE_CONNECTION_METADATA/application-role-connection-metadata-object-application-role-connection-metadata-type) | type of metadata value | +| key | string | dictionary key for the metadata field (must be `a-z`, `0-9`, or `_` characters; max 50 characters) | +| name | string | name of the metadata field (max 100 characters) | +| name_localizations? | dictionary with keys in [available locales](#DOCS_REFERENCE/locales) | translations of the name | +| description | string | description of the metadata field (max 200 characters) | +| description_localizations? | dictionary with keys in [available locales](#DOCS_REFERENCE/locales) | translations of the description | + +###### Application Role Connection Metadata Type + +| Type | Value | Description | +| ------------------------------ | ----- | -------------------------------------------------------------------------------------------------------------------------------------- | +| INTEGER_LESS_THAN_OR_EQUAL | 1 | the metadata value (`integer`) is less than or equal to the guild's configured value (`integer`) | +| INTEGER_GREATER_THAN_OR_EQUAL | 2 | the metadata value (`integer`) is greater than or equal to the guild's configured value (`integer`) | +| INTEGER_EQUAL | 3 | the metadata value (`integer`) is equal to the guild's configured value (`integer`) | +| INTEGER_NOT_EQUAL | 4 | the metadata value (`integer`) is not equal to the guild's configured value (`integer`) | +| DATETIME_LESS_THAN_OR_EQUAL | 5 | the metadata value (`ISO8601 string`) is less than or equal to the guild's configured value (`integer`; `days before current date`) | +| DATETIME_GREATER_THAN_OR_EQUAL | 6 | the metadata value (`ISO8601 string`) is greater than or equal to the guild's configured value (`integer`; `days before current date`) | +| BOOLEAN_EQUAL | 7 | the metadata value (`integer`) is equal to the guild's configured value (`integer`; `1`) | +| BOOLEAN_NOT_EQUAL | 8 | the metadata value (`integer`) is not equal to the guild's configured value (`integer`; `1`) | + +> info +> Each metadata type offers a comparison operation that allows guilds to configure role requirements based on metadata values stored by the bot. Bots specify a `metadata value` for each user and guilds specify the required `guild's configured value` within the guild role settings. + +## Get Application Role Connection Metadata Records % GET /applications/{application.id#DOCS_RESOURCES_APPLICATION/application-object}/role-connections/metadata + +Returns a list of [application role connection metadata](#DOCS_RESOURCES_APPLICATION_ROLE_CONNECTION_METADATA/application-role-connection-metadata-object) objects for the given application. + +## Update Application Role Connection Metadata Records % PUT /applications/{application.id#DOCS_RESOURCES_APPLICATION/application-object}/role-connections/metadata + +Updates and returns a list of [application role connection metadata](#DOCS_RESOURCES_APPLICATION_ROLE_CONNECTION_METADATA/application-role-connection-metadata-object) objects for the given application. + +> info +> An application can have a maximum of 5 metadata records. diff --git a/docs/resources/User.md b/docs/resources/User.md index 7c881a4f71..f6cf17ac18 100644 --- a/docs/resources/User.md +++ b/docs/resources/User.md @@ -141,6 +141,18 @@ The connection object that the user has attached. | 0 | None | invisible to everyone except the user themselves | | 1 | Everyone | visible to everyone | +### Application Role Connection Object + +The role connection object that an application has attached to a user. + +###### Application Role Connection Structure + +| Field | Type | Description | +| ----------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| platform_name | ?string | the vanity name of the platform a bot has connected (max 50 characters) | +| platform_username | ?string | the username on the platform a bot has connected (max 100 characters) | +| metadata | object | object mapping [application role connection metadata](#DOCS_RESOURCES_APPLICATION_ROLE_CONNECTION_METADATA/application-role-connection-metadata-object) keys to their `string`-ified value (max 100 characters) for the user on the platform a bot has connected | + ## Get Current User % GET /users/@me Returns the [user](#DOCS_RESOURCES_USER/user-object) object of the requester's account. For OAuth2, this requires the `identify` scope, which will return the object _without_ an email, and optionally the `email` scope, which returns the object _with_ an email. @@ -229,3 +241,19 @@ Create a new group DM channel with multiple users. Returns a [DM channel](#DOCS_ ## Get User Connections % GET /users/@me/connections Returns a list of [connection](#DOCS_RESOURCES_USER/connection-object) objects. Requires the `connections` OAuth2 scope. + +## Get User Application Role Connection % GET /users/@me/applications/{application.id#DOCS_RESOURCES_APPLICATION/application-object}/role-connection + +Returns the [application role connection](#DOCS_RESOURCES_USER/application-role-connection-object) for the user. Requires an OAuth2 access token with `role_connections.write` scope for the application specified in the path. + +## Update User Application Role Connection % PUT /users/@me/applications/{application.id#DOCS_RESOURCES_APPLICATION/application-object}/role-connection + +Updates and returns the [application role connection](#DOCS_RESOURCES_USER/application-role-connection-object) for the user. Requires an OAuth2 access token with `role_connections.write` scope for the application specified in the path. + +###### JSON Params + +| Field | Type | Description | +| ------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| platform_name? | string | the vanity name of the platform a bot has connected (max 50 characters) | +| platform_username? | string | the username on the platform a bot has connected (max 100 characters) | +| metadata? | object | object mapping [application role connection metadata](#DOCS_RESOURCES_APPLICATION_ROLE_CONNECTION_METADATA/application-role-connection-metadata-object) keys to their `string`-ified value (max 100 characters) for the user on the platform a bot has connected | diff --git a/docs/topics/OAuth2.md b/docs/topics/OAuth2.md index 774a1e642d..42713f1467 100644 --- a/docs/topics/OAuth2.md +++ b/docs/topics/OAuth2.md @@ -43,6 +43,7 @@ These are a list of all the OAuth2 scopes that Discord supports. Some scopes req | identify | allows [/users/@me](#DOCS_RESOURCES_USER/get-current-user) without `email` | | messages.read | for local rpc server api access, this allows you to read messages from all client channels (otherwise restricted to channels/guilds your app creates) | | relationships.read | allows your app to know a user's friends and implicit relationships - requires Discord approval | +| role_connections.write | allows your app to update a user's connection and metadata for the app | | rpc | for local rpc server access, this allows you to control a user's local Discord client - requires Discord approval | | rpc.activities.write | for local rpc server access, this allows you to update a user's activity - requires Discord approval | | rpc.notifications.read | for local rpc server access, this allows you to receive notifications pushed out to the user - requires Discord approval |