Skip to content

Commit

Permalink
document role connections (#5668)
Browse files Browse the repository at this point in the history 
* document role connections

* add some more copy

* fix description

* fixes

* crc
  • Loading branch information
@night
night authored Dec 12, 2022
1 parent 36085ff commit 205ceb4
Show file tree
Hide file tree
Showing 4 changed files with 102 additions and 23 deletions.
47 changes: 24 additions & 23 deletions docs/resources/Application.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
49 changes: 49 additions & 0 deletions docs/resources/Application_Role_Connection_Metadata.md
View file
Original file line number Diff line number Diff line change
@@ -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.
Loading

0 comments on commit 205ceb4

Please sign in to comment.