discord · colinloretz · Jun 17, 2024 · May 16, 2024 · May 16, 2024 · May 16, 2024
@@ -1,5 +1,21 @@
 # Change Log
 
+## Premium Interactions
+
+#### May 16, 2024
+
+**Premium Apps: New Premium Style for MessageComponentType.BUTTON**
+
+This button is to be used with `sku_id` which points to an active SKU. This allows developers to customize their premium experience.
+
+Learn more about using [Buttons](#DOCS_INTERACTIONS_MESSAGE_COMPONENTS/buttons).
+
+**Deprecates Interaction Response Type 10**
+
+The `PREMIUM_REQUIRED` interaction response type is now deprecated in favor of using custom premium buttons. This will continue to function but may be eventually unsupported. It is recommended to migrate your bots to use the premium buttons.
+
+Learn more about [Premium Interactions](#DOCS_MONETIZATION_APP_SUBSCRIPTIONS/gating-premium-interactions).
+
 ## Premium Apps: One-Time Purchases and Store
 
 #### April 24, 2024

@@ -90,21 +90,24 @@ Buttons are interactive components that render in messages. They can be clicked
 
 ###### Button Structure
 
-| Field      | Type                                                | Description                                                                         |
-|------------|-----------------------------------------------------|-------------------------------------------------------------------------------------|
-| type       | integer                                             | `2` for a button                                                                    |
-| style      | integer                                             | A [button style](#DOCS_INTERACTIONS_MESSAGE_COMPONENTS/button-object-button-styles) |
-| label?     | string                                              | Text that appears on the button; max 80 characters                                  |
-| emoji?     | partial [emoji](#DOCS_RESOURCES_EMOJI/emoji-object) | `name`, `id`, and `animated`                                                        |
-| custom_id? | string                                              | Developer-defined identifier for the button; max 100 characters                     |
-| url?       | string                                              | URL for link-style buttons                                                          |
-| disabled?  | boolean                                             | Whether the button is disabled (defaults to `false`)                                |
+| Field      | Type                                                | Description                                                                                                                                          |
+|------------|-----------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|
+| type       | integer                                             | `2` for a button                                                                                                                                     |
+| style      | integer                                             | A [button style](#DOCS_INTERACTIONS_MESSAGE_COMPONENTS/button-object-button-styles)                                                                  |
+| label?     | string                                              | Text that appears on the button; max 80 characters                                                                                                   |
+| emoji?     | partial [emoji](#DOCS_RESOURCES_EMOJI/emoji-object) | `name`, `id`, and `animated`                                                                                                                         |
+| custom_id? | string                                              | Developer-defined identifier for the button; max 100 characters                                                                                      |
+| sku_id?    | snowflake                                           | Identifier for a purchasable SKU, only available when using [ButtonStyle.Premium](#DOCS_INTERACTIONS_MESSAGE_COMPONENTS/button-object-button-styles) |
+| url?       | string                                              | URL for link-style buttons                                                                                                                           |
+| disabled?  | boolean                                             | Whether the button is disabled (defaults to `false`)                                                                                                 |
 
 Buttons come in a variety of styles to convey different types of actions. These styles also define what fields are valid for a button.
 
-- Non-link buttons **must** have a `custom_id`, and cannot have a `url`
+- Non-link and Non-premium buttons **must** have a `custom_id`, and cannot have a `url` or a `sku_id`.
 - Link buttons **must** have a `url`, and cannot have a `custom_id`
 - Link buttons do not send an [interaction](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING/interaction-object) to your app when clicked
+- Premium buttons **must** contain a `sku_id`, and cannot have a `custom_id`, `label`, `url`, or `emoji`.
+- Premium buttons do not send an [interaction](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING/interaction-object) to your app when clicked
 
 ###### Button Styles
 
@@ -115,11 +118,46 @@ Buttons come in a variety of styles to convey different types of actions. These
 | Success   | 3     | green                    | `custom_id`    |
 | Danger    | 4     | red                      | `custom_id`    |
 | Link      | 5     | grey, navigates to a URL | `url`          |
+| Premium   | 6     | gradient                 | `sku_id`       |
 
 ![An image showing the different button styles](button-styles.png)
 
 When a user clicks on a button, your app will receive an [interaction](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING/interaction-object) including the message the button was on:
 
+### Button Design Guidelines
+
+###### General Button copy
+
+- 34 characters max with icon or emoji
+- 38 characters max without icon or emoji
+- Keep text concise and to the point.
+- Use clear and easily understandable language. Avoid jargon or overly technical terms.
+- Use verbs that indicate the outcome of the action.
+- Maintain consistency in language and tone across buttons.
+- Anticipate the need for translation, test for expansion or contraction in different languages.
+
+###### Multiple Buttons
+
+Use different button styles to create a hierarchy. Use only one `Primary` button per group.
+
+![Example showing one primary button per button group](multiple-buttons-example-1.png)
+
+If there are multiple buttons of equal significance, use the `Secondary` button style for all buttons
+
+![Example showing multiple buttons in a group with equal significance](multiple-buttons-example-2.png)
+
+###### Premium Buttons
+
+Premium buttons will automatically have:
+
+- Shop Icon
+- Blurple Background
+- SKU name
+- SKU price
+- 34 character max for this button. Longer titles will be truncated
+
+![A premium button](premium-button.png)
+
 ### Component Interaction Object
 
 ###### Sample Component Interaction

@@ -209,22 +209,22 @@ There are a number of ways you can respond to an interaction:
 
 ###### Interaction Callback Type
 
-| Name                                    | Value | Description                                                                                                   |
-|-----------------------------------------|-------|---------------------------------------------------------------------------------------------------------------|
-| PONG                                    | 1     | ACK a `Ping`                                                                                                  |
-| CHANNEL_MESSAGE_WITH_SOURCE             | 4     | respond to an interaction with a message                                                                      |
-| DEFERRED_CHANNEL_MESSAGE_WITH_SOURCE    | 5     | ACK an interaction and edit a response later, the user sees a loading state                                   |
-| DEFERRED_UPDATE_MESSAGE\*               | 6     | for components, ACK an interaction and edit the original message later; the user does not see a loading state |
-| UPDATE_MESSAGE\*                        | 7     | for components, edit the message the component was attached to                                                |
-| APPLICATION_COMMAND_AUTOCOMPLETE_RESULT | 8     | respond to an autocomplete interaction with suggested choices                                                 |
-| MODAL\*\*                               | 9     | respond to an interaction with a popup modal                                                                  |
-| PREMIUM_REQUIRED\*\*\*                  | 10    | respond to an interaction with an upgrade button, only available for apps with monetization enabled           |
+| Name                                    | Value | Description                                                                                                                                              |
+|-----------------------------------------|-------|----------------------------------------------------------------------------------------------------------------------------------------------------------|
+| PONG                                    | 1     | ACK a `Ping`                                                                                                                                             |
+| CHANNEL_MESSAGE_WITH_SOURCE             | 4     | respond to an interaction with a message                                                                                                                 |
+| DEFERRED_CHANNEL_MESSAGE_WITH_SOURCE    | 5     | ACK an interaction and edit a response later, the user sees a loading state                                                                              |
+| DEFERRED_UPDATE_MESSAGE\*               | 6     | for components, ACK an interaction and edit the original message later; the user does not see a loading state                                            |
+| UPDATE_MESSAGE\*                        | 7     | for components, edit the message the component was attached to                                                                                           |
+| APPLICATION_COMMAND_AUTOCOMPLETE_RESULT | 8     | respond to an autocomplete interaction with suggested choices                                                                                            |
+| MODAL\*\*                               | 9     | respond to an interaction with a popup modal                                                                                                             |
+| PREMIUM_REQUIRED\*\*\*                  | 10    | [Deprecated](#DOCS_CHANGE_LOG/premium-interactions). respond to an interaction with an upgrade button, only available for apps with monetization enabled |
 
 \* Only valid for [component-based](#DOCS_INTERACTIONS_MESSAGE_COMPONENTS/) interactions
 
 \*\* Not available for `MODAL_SUBMIT` and `PING` interactions.
 
-\*\*\* Not available for `APPLICATION_COMMAND_AUTOCOMPLETE` and `PING` interactions.
+\*\*\* This response type is deprecated. Learn more about [migrating to premium buttons](#DOCS_MONETIZATION_APP_SUBSCRIPTIONS/gating-premium-interactions). `PREMIUM_REQUIRED` response type is not available for `APPLICATION_COMMAND_AUTOCOMPLETE` and `PING` interactions.
 
 ###### Interaction Callback Data Structure
 

@@ -36,6 +36,34 @@ When a user subscribes to your app, there are a few things you will need to impl
 
 ### Gating Premium Interactions
 
+Each interaction payload includes an `entitlements` field containing an array of full [entitlement objects](#DOCS_MONETIZATION_ENTITLEMENTS/entitlement-object). You can use this field to determine if the user or guild is subscribed to your app. If the user or guild is not subscribed and you wish to present them with a means to do so you can use a [button](#DOCS_INTERACTIONS_MESSAGE_COMPONENTS/buttons) with a [premium style](#DOCS_INTERACTIONS_MESSAGE_COMPONENTS/button-object-button-styles) and a `sku_id` attached. You may also use these buttons to present users with options to make a [One-Time Purchase](#DOCS_MONETIZATION_ONE-TIME_PURCHASES).
 If someone is already subscribed, this command will show the upgrade prompt with a disabled upgrade button. In order to avoid this, your interaction handler should check to see if the user or guild has an active entitlement for your SKU. 
 Each interaction payload includes an `entitlements` field containing an array of full [entitlement objects](#DOCS_MONETIZATION_ENTITLEMENTS/entitlement-object). 
 You can use this field to determine if the user or guild is subscribed to your app. 
 If someone is already subscribed, this command will show the upgrade prompt with a disabled upgrade button. In order to avoid this, your interaction handler should check to see if the user or guild has an active entitlement for your SKU. 
  
 Each interaction payload includes an `entitlements` field containing an array of full [entitlement objects](#DOCS_MONETIZATION_ENTITLEMENTS/entitlement-object). 
  
 You can use this field to determine if the user or guild is subscribed to your app. 
+
+```javascript
+return new JsonResponse({
+    type: 4, // InteractionResponseType.CHANNEL_MESSAGE_WITH_SOURCE
+    data: {
+        content: "This command requires Nelly Premium! Upgrade now to get access to these features!",
+        components: [{
+            type: MessageComponentTypes.ACTION_ROW,
+            components: [
+                {
+                    type: MessageComponentTypes.BUTTON,
+                    style: 6, // ButtonStyleTypes.PREMIUM
+                    skuId: '1234965026943668316',
+                },
+            ],
+        }]
+    },
+});
+```
+
+![A premium button](premium-button.png)
+
+#### Type 10 Interaction Response
+
+> warn
+> `PREMIUM_REQUIRED` type 10 interaction response is deprecated. Please use `ButtonStyle.PREMIUM` to handle purchases.
+
 Interactions like [commands](#DOCS_INTERACTIONS_APPLICATION_COMMANDS) commonly respond to users with a message or modal response. If you'd like to make a command only available to users with a subscription, you can reply with a `PREMIUM_REQUIRED` interaction response `type: 10`. Users without a subscription will be prompted to upgrade when they attempt to use these commands.
 
 ```javascript
@@ -94,4 +122,4 @@ After checkout, you will have a live subscription that includes a `starts_at` an
 
 Once an app has made its first $100 it will become eligible for payout. A review will be conducted and if everything looks good, your team will begin to receive payouts.
 
-For more information, read the [Premium Apps Payouts](https://support-dev.discord.com/hc/articles/17299902720919) Help Center article.
+For more information, read the [Premium Apps Payouts](https://support-dev.discord.com/hc/articles/17299902720919) Help Center article.