diff --git a/docs/change-log/2017-07-24-new-feature-audit-logs.md b/docs/change-log/2017-07-24-new-feature-audit-logs.md index 20adb712b5..97ea39fb13 100644 --- a/docs/change-log/2017-07-24-new-feature-audit-logs.md +++ b/docs/change-log/2017-07-24-new-feature-audit-logs.md @@ -3,4 +3,4 @@ title: "New Feature: Audit Logs" date: "2017-07-24" --- -Audit logs are here! Well, they've been here all along, but now we've got [documentation](/docs/resources/audit-log#) about them. Check it out, but remember: with great power comes great responsibility. +Audit logs are here! Well, they've been here all along, but now we've got [documentation](/docs/resources/audit-log) about them. Check it out, but remember: with great power comes great responsibility. diff --git a/docs/change-log/2018-01-23-deprecation-accept-invite-endpoint.md b/docs/change-log/2018-01-23-deprecation-accept-invite-endpoint.md index bbe90eb48f..2a7a136698 100644 --- a/docs/change-log/2018-01-23-deprecation-accept-invite-endpoint.md +++ b/docs/change-log/2018-01-23-deprecation-accept-invite-endpoint.md @@ -3,4 +3,4 @@ title: "Deprecation: Accept Invite Endpoint" date: "2018-01-23" --- -The [Accept Invite](/docs/resources/invite#) endpoint is deprecated starting today, and will be discontinued on March 23, 2018. The [Add Guild Member](/docs/resources/guild#add-guild-member) endpoint should be used in its place. +The [Accept Invite](/docs/resources/invite) endpoint is deprecated starting today, and will be discontinued on March 23, 2018. The [Add Guild Member](/docs/resources/guild#add-guild-member) endpoint should be used in its place. diff --git a/docs/change-log/2019-08-12-more-precise-rate-limits.md b/docs/change-log/2019-08-12-more-precise-rate-limits.md index 84e96dd6f2..266c53cf19 100644 --- a/docs/change-log/2019-08-12-more-precise-rate-limits.md +++ b/docs/change-log/2019-08-12-more-precise-rate-limits.md @@ -3,4 +3,4 @@ title: "More Precise Rate Limits" date: "2019-08-12" --- -You can now get more precise rate limit reset times, via a new request header. Check out the [rate limits](/docs/topics/rate-limits#) documentation for more information. +You can now get more precise rate limit reset times, via a new request header. Check out the [rate limits](/docs/topics/rate-limits) documentation for more information. diff --git a/docs/change-log/2020-12-15-slash-commands-and-interactions.md b/docs/change-log/2020-12-15-slash-commands-and-interactions.md index 3c0dd62836..a04de4e9d7 100644 --- a/docs/change-log/2020-12-15-slash-commands-and-interactions.md +++ b/docs/change-log/2020-12-15-slash-commands-and-interactions.md @@ -3,7 +3,7 @@ title: "Slash Commands and Interactions" date: "2020-12-15" --- -Slash Commands are here! There's a *lot* to cover, so go check out specific documentation under [Slash Commands](/docs/interactions/application-commands#). +Slash Commands are here! There's a *lot* to cover, so go check out specific documentation under [Slash Commands](/docs/interactions/application-commands). Slash Commands include some new features for webhooks as well: diff --git a/docs/change-log/2021-05-26-buttons-and-message-components.md b/docs/change-log/2021-05-26-buttons-and-message-components.md index 108ad7ec88..5b73b6eda9 100644 --- a/docs/change-log/2021-05-26-buttons-and-message-components.md +++ b/docs/change-log/2021-05-26-buttons-and-message-components.md @@ -5,7 +5,7 @@ date: "2021-05-26" Message components are now available with our first two components: a layout-based `ActionRow` and...buttons! -You can now include buttons on messages sent by your app, whether they're bot messages or responses to interactions. [Learn more about message components](/docs/interactions/message-components#). +You can now include buttons on messages sent by your app, whether they're bot messages or responses to interactions. [Learn more about message components](/docs/components/overview). The addition of message components means new fields and response types: diff --git a/docs/change-log/2021-06-30-select-menu-components.md b/docs/change-log/2021-06-30-select-menu-components.md index f5f035cacc..2a1aab356d 100644 --- a/docs/change-log/2021-06-30-select-menu-components.md +++ b/docs/change-log/2021-06-30-select-menu-components.md @@ -5,4 +5,4 @@ date: "2021-06-30" Select Menus are now part of the components API! They're the greatest thing since the invention of buttons yesterday. Select menus allow you to offer users a choice of one or many options in a friendly UI-based way. -Select menus can be used like other [message components](/docs/interactions/message-components#). Learn all the specifics in the [documentation](/docs/interactions/message-components#select-menus). +Select menus can be used like other [message components](/docs/components/overview). Learn all the specifics in the [documentation](/docs/components/reference#string-select). diff --git a/docs/change-log/2022-10-13-new-select-menu-components.md b/docs/change-log/2022-10-13-new-select-menu-components.md index 663d95d49e..96c75b3a9a 100644 --- a/docs/change-log/2022-10-13-new-select-menu-components.md +++ b/docs/change-log/2022-10-13-new-select-menu-components.md @@ -3,13 +3,13 @@ title: "New Select Menu Components" date: "2022-10-13" --- -Four new select menu [component types](/docs/interactions/message-components#component-object-component-types) have been added to make it easier to populate selects with common resources in Discord: +Four new select menu [component types](/docs/components/reference#component-object-component-types) have been added to make it easier to populate selects with common resources in Discord: * User select (type `5`) * Role select (type `6`) * Mentionable (user *and* role) select (type `7`) * Channel select (type `8`) -The new select menu components are defined similarly to the existing string select menu—with the exception of not including the `options` field and, within channel select menus, having the option to include a `channel_types` field. The [select menu interaction](/docs/interactions/message-components#select-menu-object-select-menu-interaction) apps receive also contain a [`resolved` field](/docs/interactions/message-components#select-menu-object-select-menu-resolved-object) for the new components. +The new select menu components are defined similarly to the existing string select menu—with the exception of not including the `options` field and, within channel select menus, having the option to include a `channel_types` field. The [select menu interaction](/docs/components/reference#string-select-string-select-interaction) apps receive also contain a [`resolved` field](/docs/components/reference#string-select-select-menu-resolved-object) for the new components. -More details can be found in the updated [select menu documentation](/docs/interactions/message-components#select-menus). +More details can be found in the updated [select menu documentation](/docs/components/reference#component-object-component-types). diff --git a/docs/change-log/2023-09-22-default-value-in-auto-populated-select-menus.md b/docs/change-log/2023-09-22-default-value-in-auto-populated-select-menus.md index 96ad53cf1a..6a4713319c 100644 --- a/docs/change-log/2023-09-22-default-value-in-auto-populated-select-menus.md +++ b/docs/change-log/2023-09-22-default-value-in-auto-populated-select-menus.md @@ -3,4 +3,4 @@ title: "Default Value in Auto-populated Select Menus" date: "2023-09-22" --- -A new `default_values` field was added for user (`5`), role (`6`), mentionable (`7`), and channel (`8`) [select menu components](/docs/interactions/message-components#select-menus). `default_values` is a list of [default value objects](/docs/interactions/message-components#select-menu-object-select-default-value-structure), which each include an `id` (the snowflake value for the resource), as well as a corresponding `type` (either `"user"`, `"role"`, or `"channel"`). +A new `default_values` field was added for user (`5`), role (`6`), mentionable (`7`), and channel (`8`) [select menu components](/docs/components/reference). `default_values` is a list of [default value objects](/docs/components/reference#user-select-select-default-value-structure), which each include an `id` (the snowflake value for the resource), as well as a corresponding `type` (either `"user"`, `"role"`, or `"channel"`). diff --git a/docs/change-log/2023-09-26-premium-app-subscriptions-available-in-the-us.md b/docs/change-log/2023-09-26-premium-app-subscriptions-available-in-the-us.md index fa0aaaddfc..ac26f16d98 100644 --- a/docs/change-log/2023-09-26-premium-app-subscriptions-available-in-the-us.md +++ b/docs/change-log/2023-09-26-premium-app-subscriptions-available-in-the-us.md @@ -17,6 +17,6 @@ Starting today, eligible US-based developers can monetize their verified apps wi * [Delete Test Entitlement](/docs/resources/entitlement#delete-test-entitlement) `DELETE /applications//entitlements/` * [Gateway Events](/docs/events/gateway-events#entitlements) for working with entitlements: `ENTITLEMENT_CREATE`, `ENTITLEMENT_UPDATE`, `ENTITLEMENT_DELETE` * New [`PREMIUM_REQUIRED (10)` interaction response type](/docs/interactions/receiving-and-responding#interaction-response-object-interaction-callback-type) is available to prompt users to upgrade -* New `entitlements` field, which is an array of [entitlement](/docs/resources/entitlement#) objects, available in interaction data payloads when [receiving and responding to interactions](/docs/interactions/receiving-and-responding#interaction-object-interaction-structure) +* New `entitlements` field, which is an array of [entitlement](/docs/resources/entitlement) objects, available in interaction data payloads when [receiving and responding to interactions](/docs/interactions/receiving-and-responding#interaction-object-interaction-structure) To learn more about eligibility details and how to enable monetization for your app, check out the [Monetization Overview](/docs/monetization/overview). diff --git a/docs/change-log/2024-06-17-premium-apps-new-premium-button-style-deep-linking-url-schemes.md b/docs/change-log/2024-06-17-premium-apps-new-premium-button-style-deep-linking-url-schemes.md index ac00de8322..0fc8dc6306 100644 --- a/docs/change-log/2024-06-17-premium-apps-new-premium-button-style-deep-linking-url-schemes.md +++ b/docs/change-log/2024-06-17-premium-apps-new-premium-button-style-deep-linking-url-schemes.md @@ -5,15 +5,15 @@ date: "2024-06-17" **New Premium Button Style** -Introduces a new `premium` [button style](/docs/interactions/message-components#button-object-button-styles) to be used with a `sku_id` which points to an active [SKU](/docs/resources/sku#sku-object). This allows developers to customize their premium experience by returning specific subscription or one-time purchase products. +Introduces a new `premium` [button style](/docs/components/reference#button-button-styles) to be used with a `sku_id` which points to an active [SKU](/docs/resources/sku#sku-object). This allows developers to customize their premium experience by returning specific subscription or one-time purchase products. -Learn more about using [button components with interactions](/docs/interactions/message-components#buttons). +Learn more about using [button components with interactions](/docs/components/reference#button). :::warn This change deprecates Interaction Response Type 10 ::: -The `PREMIUM_REQUIRED (10)` 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 more flexible [premium button component](/docs/interactions/message-components#button-object-button-styles). +The `PREMIUM_REQUIRED (10)` 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 more flexible [premium button component](/docs/components/reference#button-button-styles). Learn more about [gating features with premium interactions](/docs/monetization/implementing-app-subscriptions#prompting-users-to-subscribe). diff --git a/docs/change-log/2025-04-22-components-v2.md b/docs/change-log/2025-04-22-components-v2.md new file mode 100644 index 0000000000..176a84e646 --- /dev/null +++ b/docs/change-log/2025-04-22-components-v2.md @@ -0,0 +1,61 @@ +--- +title: "Introducing New Components for Messages!" +date: "2025-04-22" +topics: +- "User Apps" +- "HTTP API" +- "Interactions" +--- + +We're bringing new components to messages that you can use in your apps. They allow you to have full control over the layout of your messages. + +#### Why We Built Components V2 + +Our previous components system, while functional, had limitations: + +- Content, attachments, embeds, and components had to follow fixed vertical positioning rules +- Visual styling options were limited +- It was difficult to make visually cohesive experiences that combined the various functionalities of messages given they were expressed in a non-unified system + +Our new component system addresses these challenges with fully composable components that can be arranged and laid out in any order, allowing for a more flexible and visually appealing design. + +#### What's New + +[Components V2](/docs/components/overview) introduces several new component types that can be used in messages: + +#### New Layout Components + +- [**Section**](/docs/components/reference#section) - Combine text with an accessory component for contextually linked elements +- [**Container**](/docs/components/reference#container) - Create visually distinct groupings with a customizable accent color +- [**Separator**](/docs/components/reference#separator) - Add visual spacing and dividers between components + +#### New Content Components + +- [**Text Display**](/docs/components/reference#text-display) - Add rich markdown-formatted text anywhere in your messages +- [**Thumbnail**](/docs/components/reference#thumbnail) - An image used in a [section](/docs/components/reference#section) +- [**Media Gallery**](/docs/components/reference#media-gallery) - Present collections of images and videos in an organized grid +- [**File**](/docs/components/reference#file) - Embed file attachments as part of your message layout + +#### Getting Started + +To use the new components, you'll need to send the message flag `1 << 15` (`IS_COMPONENTS_V2`) which activates the components system on a per-message basis. + +We've created guides to help you implement these new features: + +- [Using Message Components](/docs/components/using-message-components) - Learn how to build rich message layouts with components +- [Using Modal Components](/docs/components/using-modal-components) - Create interactive forms and dialogs + +#### Compatibility Notes + +[Legacy component behavior](/docs/components/reference#legacy-message-component-behavior) will continue to work as before, so your existing integrations won't break. However, when using the Components V2 flag, you'll need to adapt to a few changes: + +- The `content` and `embeds` fields will no longer work but you'll be able to use [Text Display](/docs/components/reference#text-display) and [Container](/docs/components/reference#container) as replacements +- Attachments need to be exposed through components to be visible. You can use a [Media Gallery](/docs/components/reference#media-gallery), [Thumbnail](/docs/components/reference#thumbnail), or [File](/docs/components/reference#file) component to display them +- The `poll` and `stickers` fields are disabled +- A max of 10 top-level components and 30 total components in a message + +#### Developer Resources + +Check out our [Component Reference](/docs/components/reference) for detailed specifications on all available components. + +We can't wait to see what you build! \ No newline at end of file diff --git a/docs/components/overview.mdx b/docs/components/overview.mdx new file mode 100644 index 0000000000..10050482b9 --- /dev/null +++ b/docs/components/overview.mdx @@ -0,0 +1,44 @@ +--- +sidebar_label: Overview +showTOC: false +--- + +# Components Overview + +Components allow you to add interactive elements to modals and the messages your app sends. They're accessible, customizable, and easy to use. + +![](images/components/hero.png) + +Discord apps support three types of message components: layout components, content components, and interactive components. Each type of component has its own purpose and use cases. + +- **Layout Components**: These components are used to organize and structure the content of your message. They help create a visually appealing and user-friendly layout. +- **Content Components**: These components are used to display information and content in your message. They can include text, images, and other media. +- **Interactive Components**: These components allow users to interact with your message. They can include buttons, select menus, and other interactive elements. + +All components are customizable and can be organized using layout components to create rich, interactive message experiences. + +To use components, messages must be sent with the `IS_COMPONENTS_V2` flag (`1<<15`). Note that using this flag disables traditional content and embeds - all content must be sent as components instead. + +:::info +[Legacy message component behavior](/docs/components/reference#legacy-message-component-behavior) will **not** be deprecated and will continue to be available to your apps on a message-by-message basis. However, we recommend using the new components for new projects and features. +::: + + + + A guide on sending Message Components with examples. + + + A guide on sending Modal Components with examples. + + + Explore the Components reference documentation. + + + +--- + +## Get Help & Join the Community + +Do you have a question or want to connect with other app developers? + +- Join our [DDevs Discord Server](https://discord.gg/discord-developers) and get help from the community, share best practices, and discover new ways to enhance your apps. \ No newline at end of file diff --git a/docs/components/reference.mdx b/docs/components/reference.mdx new file mode 100644 index 0000000000..90fc2a2ff7 --- /dev/null +++ b/docs/components/reference.mdx @@ -0,0 +1,1194 @@ +--- +sidebar_label: Component Reference +--- + +# Component Reference + +This document serves as a comprehensive reference for all available components. It covers three main categories: + +- **Layout Components** - For organizing and structuring content (Action Rows, Sections, Containers) +- **Content Components** - For displaying static text, images, and files (Text Display, Media Gallery, Thumbnails) +- **Interactive Components** - For user interactions (Buttons, Select Menus, Text Input) + +To use these components, you need to send the [message flag](/docs/resources/message#message-object-message-flags) `1 << 15` (IS_COMPONENTS_V2) which can be sent on a per-message basis. This enables the new components system with the following changes: + +- The `content` and `embeds` fields will no longer work but you'll be able to use [Text Display](/docs/components/reference#text-display) and [Container](/docs/components/reference#container) as replacements +- Attachments won't show by default - they must be exposed through components +- The `poll` and `stickers` fields are disabled +- A max of 10 top-level components and 30 total components in a message + +:::info +[Legacy component behavior](/docs/components/reference#legacy-message-component-behavior) will continue to work but provide less flexibility and control over the message layout. +::: + +For a practical guide on implementing these components, see our [Using Message Components](/docs/components/using-message-components) and [Using Modal Components](/docs/components/using-modal-components) documentation. + +--- + +## What is a Component + +Components allow you to style and structure your messages, modals, and interactions. They are interactive elements that can create rich user experiences in your Discord applications. + +Components are a field on the [message object](/docs/resources/message#message-object) and [modal](/docs/interactions/receiving-and-responding#interaction-response-object-modal). You can use them when creating messages or responding to an interaction, like an [application command](/docs/interactions/application-commands). + +### Component Object + +###### Component Types + +The following is a complete table of available components. Details about each component are in the sections below. + +| Type | Name | Description | Style | Usage | +|------|---------------------------------------------------------------------|------------------------------------------------------------|-------------|----------------| +| 1 | [Action Row](/docs/components/reference#action-row) | Container to display a row of interactive components | Layout | Message, Modal | +| 2 | [Button](/docs/components/reference#button) | Button object | Interactive | Message | +| 3 | [String Select](/docs/components/reference#string-select) | Select menu for picking from defined text options | Interactive | Message | +| 4 | [Text Input](/docs/components/reference#text-input) | Text input object | Interactive | Modal | +| 5 | [User Select](/docs/components/reference#user-select) | Select menu for users | Interactive | Message | +| 6 | [Role Select](/docs/components/reference#role-select) | Select menu for roles | Interactive | Message | +| 7 | [Mentionable Select](/docs/components/reference#mentionable-select) | Select menu for mentionables (users *and* roles) | Interactive | Message | +| 8 | [Channel Select](/docs/components/reference#channel-select) | Select menu for channels | Interactive | Message | +| 9 | [Section](/docs/components/reference#section) | Container to display text alongside an accessory component | Layout | Message | +| 10 | [Text Display](/docs/components/reference#text-display) | Markdown text | Content | Message | +| 11 | [Thumbnail](/docs/components/reference#thumbnail) | Small image that can be used as an accessory | Content | Message | +| 12 | [Media Gallery](/docs/components/reference#media-gallery) | Display images and other media | Content | Message | +| 13 | [File](/docs/components/reference#file) | Displays an attached file | Content | Message | +| 14 | [Separator](/docs/components/reference#separator) | Component to add vertical padding between other components | Layout | Message | +| 17 | [Container](/docs/components/reference#container) | Container that visually groups a set of components | Layout | Message | + +## Anatomy of a Component + +All components have the following fields: + +| Field | Type | Description | +|-------|---------|------------------------------------------------------------------------------------------| +| type | integer | The [type](/docs/components/reference#component-object-component-types) of the component | +| id? | integer | 32 bit integer used as an optional identifier for component | + +The `id` field is optional and is used to identify components in the response from an interaction that aren't interactive components. The `id` must be unique within the message and is generated sequentially if left empty. Generation of `id`s won't use another `id` that exists in the message if you have one defined for another component. + +###### Custom ID + +Additionally, interactive components like buttons and selects must have a `custom_id` field. The developer defines this field when sending the component payload, and it is returned in the interaction payload sent when a user interacts with the component. For example, if you set `custom_id: click_me` on a button, you'll receive an interaction containing `custom_id: click_me` when a user clicks that button. + +`custom_id` is only available on interactive components and must be unique per component. Multiple components on the same message must not share the same `custom_id`. This field is a string of a maximum of 100 characters and can be used flexibly to maintain state or pass through other important data. + +| Field | Type | Description | +|-----------|--------|--------------------------------------------------| +| custom_id | string | Developer-defined identifier, max 100 characters | + +## Action Row + +An Action Row is a top-level layout component used in messages and modals. + +Action Rows can contain: + +- Up to 5 contextually grouped [buttons](/docs/components/reference#button) +- A single [text input](/docs/components/reference#text-input) +- A single select component ([string select](/docs/components/reference#string-select), [user select](/docs/components/reference#user-select), [role select](/docs/components/reference#role-select), [mentionable select](/docs/components/reference#mentionable-select), or [channel select](/docs/components/reference#channel-select)) + +###### Action Row Structure + +| Field | Type | Description | +|------------|-------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------| +| type | integer | `1` for action row component | +| id? | integer | Optional identifier for component | +| components | array of [component objects](/docs/components/reference#component-object-component-types) | Up to 5 interactive [button](/docs/components/reference#button) components or a single [select](/docs/components/reference#user-select) component | + +###### Example + +```json +"components": +[ + { + "type": 1, + "components": [ + { + "type": 2, + "label": "Accept", + "style": 1, + "custom_id": "click_yes" + }, + { + "type": 2, + "label": "Learn More", + "style": 5, + "url": "http://watchanimeattheoffice.com/" + }, + { + "type": 2, + "label": "Decline", + "style": 4, + "custom_id": "click_no" + } + ] + } +] +``` + +![Example of an Action Row with three buttons](images/components/action-row.png) + +## Button + +A Button is an interactive component that can only be used in messages. It creates clickable elements that users can interact with, sending an [interaction](/docs/interactions/receiving-and-responding#interaction-object) to your app when clicked. + +Buttons must be placed inside an [Action Row](/docs/components/reference#action-row) or a [Section](/docs/components/reference#section)'s `accessory` field. + +###### Button Structure + +| Field | Type | Description | +|-----------|-----------------------------------------------------|---------------------------------------------------------------------------------------------------------------------| +| type | integer | `2` for a button | +| id? | integer | Optional identifier for component | +| style | integer | A [button style](/docs/components/reference#button-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](/docs/resources/sku#sku-object), only available when using premium-style buttons | +| url? | string | URL for link-style buttons | +| disabled? | boolean | Whether the button is disabled (defaults to `false`) | + +Buttons come in various styles to convey different types of actions. These styles also define what fields are valid for a button. + +- 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 + +| Name | Value | Action | Required Field | +|-----------|-------|----------------------------------------------------------------|----------------| +| Primary | 1 | The most important or recommended action in a group of options | `custom_id` | +| Secondary | 2 | Alternative or supporting actions | `custom_id` | +| Success | 3 | Positive confirmation or completion actions | `custom_id` | +| Danger | 4 | An action with irreversible consequences | `custom_id` | +| Link | 5 | Navigates to a URL | `url` | +| Premium | 6 | Purchase | `sku_id` | + +###### Example + +```json +"components": +[ + { + "type": 1, + "components": [ + { + "type": 2, + "label": "Click me!", + "style": 1, + "custom_id": "clicked_me" + }, + ] + } +] +``` + +###### Button Interaction + +```json +{ + "version": 1, + "type": 3, + "token": "unique_interaction_token", + "message": { + "type": 0, + "tts": false, + "timestamp": "2021-05-19T02:12:51.710000+00:00", + "pinned": false, + "mentions": [], + "mention_roles": [], + "mention_everyone": false, + "id": "844397162624450620", + "flags": 32768, + "edited_timestamp": null, + "components": [ + { + "type": 10, + "content": "This is a message with components." + }, + { + "type": 1, + "components": [ + { + "type": 2, + "label": "Click me!", + "style": 1, + "custom_id": "click_one" + } + ] + } + ], + "channel_id": "345626669114982402", + "author": { + "username": "Mason", + "public_flags": 131141, + "id": "53908232506183680", + "discriminator": "1337", + "avatar": "a_d5efa99b3eeaa7dd43acca82f5692432" + }, + "attachments": [] + }, + "member": { + "user": { + "username": "Mason", + "public_flags": 131141, + "id": "53908232506183680", + "discriminator": "1337", + "avatar": "a_d5efa99b3eeaa7dd43acca82f5692432" + }, + "roles": [ + "290926798626357999" + ], + "premium_since": null, + "permissions": "17179869183", + "pending": false, + "nick": null, + "mute": false, + "joined_at": "2017-03-13T19:19:14.040000+00:00", + "is_pending": false, + "deaf": false, + "avatar": null + }, + "id": "846462639134605312", + "guild_id": "290926798626357999", + "data": { + "custom_id": "click_one", + "component_type": 2 + }, + "channel_id": "345626669114982999", + "application_id": "290926444748734465" +} +``` + +### Button Design Guidelines + +###### General Button Content + +- 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 and 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](images/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](images/multiple-buttons-example-2.png) + +###### Premium Buttons + +Premium buttons will automatically have the following: + +- Shop Icon +- SKU name +- SKU price + +![A premium button](images/premium-button.png) + +## String Select + +A String Select is an interactive component that allows users to select one or more provided `options` in a message. + +String Selects can be configured for both single-select and multi-select behavior. When a user finishes making their choice(s) your app receives an [interaction](/docs/interactions/receiving-and-responding#interaction-object-interaction-structure). + +String Selects must be placed inside an [Action Row](/docs/components/reference#action-row) and are only available in messages. An Action Row can contain only one select menu and cannot contain buttons if it has a select menu. + + +###### String Select Structure + +| Field | Type | Description | +|--------------|---------------------------------------------------------------------------------------------|----------------------------------------------------------------------------| +| type | integer | `3` for string select | +| id? | integer | Optional identifier for component | +| custom_id | string | ID for the select menu; max 100 characters | +| options | array of [select options](/docs/components/reference#string-select-select-option-structure) | Specified choices in a select menu; max 25 | +| placeholder? | string | Placeholder text if nothing is selected or default; max 150 characters | +| min_values? | integer | Minimum number of items that must be chosen (defaults to 1); min 0, max 25 | +| max_values? | integer | Maximum number of items that can be chosen (defaults to 1); max 25 | +| disabled? | boolean | Whether select menu is disabled (defaults to `false`) | + +###### Select Option Structure + +| Field | Type | Description | +|--------------|------------------------------------------------------------|----------------------------------------------------------| +| label | string | User-facing name of the option; max 100 characters | +| value | string | Dev-defined value of the option; max 100 characters | +| description? | string | Additional description of the option; max 100 characters | +| emoji? | partial [emoji](/docs/resources/emoji#emoji-object) object | `id`, `name`, and `animated` | +| default? | boolean | Will show this option as selected by default | + +###### Example + +```json +"components": [ + { + "type": 3, + "custom_id": "string_select", + "placeholder": "Favorite bug?", + "options": [ + { + "label": "Ant", + "value": "ant", + "description": "(best option)", + "emoji": {"name": "🐜"} + }, + { + "label": "Butterfly", + "value": "butterfly", + "emoji": {"name": "🦋"} + }, + { + "label": "Catarpillar", + "value": "caterpillar", + "emoji": {"name": "🐛"} + } + ] + } +] +``` + +![Example of a String Select with three options](images/components/string-select.png) + +###### String Select Interaction + +```json +{ + "application_id": "845027738276462632", + "channel_id": "772908445358620702", + "data": { + "component_type":3, + "custom_id": "class_select_1", + "values": [ + "mage", + "rogue" + ] + }, + "guild_id": "772904309264089089", + "id": "847587388497854464", + "member": { + "avatar": null, + "deaf": false, + "is_pending": false, + "joined_at": "2020-11-02T19:25:47.248000+00:00", + "mute": false, + "nick": "Bot Man", + "pending": false, + "permissions": "17179869183", + "premium_since": null, + "roles": [ + "785609923542777878" + ], + "user":{ + "avatar": "a_d5efa99b3eeaa7dd43acca82f5692432", + "discriminator": "1337", + "id": "53908232506183680", + "public_flags": 131141, + "username": "Mason" + } + }, + "message":{ + "application_id": "845027738276462632", + "attachments": [], + "author": { + "avatar": null, + "bot": true, + "discriminator": "5284", + "id": "845027738276462632", + "public_flags": 0, + "username": "Interactions Test" + }, + "channel_id": "772908445358620702", + "components": [ + { + "type": 10, + "content": "Mason is looking for new arena partners. What classes do you play?" + }, + { + "type": 1, + "components": [ + { + "type": 3, + "placeholder": "Choose a class", + "custom_id": "class_select_1", + "max_values": 1, + "min_values": 1, + "options": [ + { + "description": "Sneak n stab", + "emoji":{ + "id": "625891304148303894", + "name": "rogue" + }, + "label": "Rogue", + "value": "rogue" + }, + { + "description": "Turn 'em into a sheep", + "emoji":{ + "id": "625891304081063986", + "name": "mage" + }, + "label": "Mage", + "value": "mage" + }, + { + "description": "You get heals when I'm done doing damage", + "emoji":{ + "id": "625891303795982337", + "name": "priest" + }, + "label": "Priest", + "value": "priest" + } + ], + } + ], + } + ], + "edited_timestamp": null, + "flags": 32768, + "id": "847587334500646933", + "interaction": { + "id": "847587333942935632", + "name": "dropdown", + "type": 2, + "user": { + "avatar": "a_d5efa99b3eeaa7dd43acca82f5692432", + "discriminator": "1337", + "id": "53908232506183680", + "public_flags": 131141, + "username": "Mason" + } + }, + "mention_everyone": false, + "mention_roles":[], + "mentions":[], + "pinned": false, + "timestamp": "2021-05-27T21:29:27.956000+00:00", + "tts": false, + "type": 20, + "webhook_id": "845027738276462632" + }, + "token": "UNIQUE_TOKEN", + "type": 3, + "version": 1 +} +``` + +###### Select Menu Resolved Object + +The `resolved` object is included in interaction payloads for user, role, mentionable, and channel select menu components. `resolved` contains a nested object with additional details about the selected options with the key of the resource type—`users`, `roles`, `channels`, and `members`. + +:::info +`members` and `users` may both be present in the `resolved` object when a user is selected (in either a [user select](/docs/components/reference#user-select) or [mentionable select](/docs/components/reference#mentionable-select)). +::: + +###### Example Resolved Object + +A sample `data` object (a subset of the interaction payload) for a channel select menu component: + +```json +{ + "component_type": 8, + "custom_id": "my_channel_select", + "resolved": { + "channels": { + "986678954901234567": { + "id": "986678954901234567", + "name": "general", + "permissions": "4398046511103", + "type": 0 + } + } + }, + "values": [ + "986678954901234567" + ] +} +``` + +## Text Input + +Text Input is an interactive component that allows users to enter free-form text responses in modals. It supports both short, single-line inputs and longer, multi-line paragraph inputs. + +Text Inputs can only be used within modals and must be placed inside an [Action Row](/docs/components/reference#action-row). + +When defining a text input component, you can set attributes to customize the behavior and appearance of it. However, not all attributes will be returned in the [text input interaction payload](/docs/components/reference#text-input-text-input-interaction). + +###### Text Input Structure + +| Field | Type | Description | +|--------------|---------|---------------------------------------------------------------------------------| +| type | integer | `4` for a text input | +| id? | integer | Optional identifier for component | +| custom_id | string | Developer-defined identifier for the input; max 100 characters | +| style | integer | The [Text Input Style](/docs/components/reference#text-input-text-input-styles) | +| label | string | Label for this component; max 45 characters | +| min_length? | integer | Minimum input length for a text input; min 0, max 4000 | +| max_length? | integer | Maximum input length for a text input; min 1, max 4000 | +| required? | boolean | Whether this component is required to be filled (defaults to `true`) | +| value? | string | Pre-filled value for this component; max 4000 characters | +| placeholder? | string | Custom placeholder text if the input is empty; max 100 characters | + +###### Text Input Styles + +| Name | Value | Description | +|-----------|-------|-------------------| +| Short | 1 | Single-line input | +| Paragraph | 2 | Multi-line input | + +###### Example + +```json +// this is a modal +{ + "title": "My Cool Modal", + "custom_id": "cool_modal", + "components": [{ + "type": 1, + "components": [{ + "type": 4, + "custom_id": "name", + "label": "Name", + "style": 1, + "min_length": 1, + "max_length": 4000, + "placeholder": "John", + "required": true + }] + }] +} +``` + +![A text input in a modal on desktop client](images/modal-desktop.png) + +###### Text Input Interaction + +```json +{ + "application_id": "845027738276462632", + "channel": { + "flags": 0, + "guild_id": "772904309264089089", + "id": "772908445358620702", + "last_message_id": "113817814796417433", + "name": "general", + "nsfw": false, + "parent_id": "1113560261366927532", + "permissions": "281474976710655", + "position": 0, + "rate_limit_per_user": 0, + "topic": null, + "type": 0 + }, + "channel_id": "772908445358620702", + "data": { + "components": [ + { + "type": 1, + "components": [ + { + "custom_id": "name", + "type": 4, + "value": "John" + } + ] + } + ], + "custom_id": "cool_modal" + }, + "guild_id": "772904309264089089", + "id": "847587388497854464", + "member": { + "avatar": null, + "deaf": false, + "is_pending": false, + "joined_at": "2020-11-02T19:25:47.248000+00:00", + "mute": false, + "nick": null, + "pending": false, + "permissions": "17179869183", + "premium_since": null, + "roles": ["785609923542777878"], + "user": { + "avatar": "a_d5efa99b3eeaa7dd43acca82f5692432", + "global_name": "Mason", + "discriminator": "0", + "id": "53908232506183680", + "public_flags": 131141, + "username": "Mason" + } + }, + "token": "UNIQUE_TOKEN", + "type": 5, + "version": 1 +} +``` + +## User Select + +A User Select is an interactive component that allows users to select one or more users in a message. Options are automatically populated based on the server's available users. + +User Selects can be configured for both single-select and multi-select behavior. When a user finishes making their choice(s) your app receives an [interaction](/docs/interactions/receiving-and-responding#interaction-object-interaction-structure). + +User Selects must be placed inside an [Action Row](/docs/components/reference#action-row) and are only available in messages. An Action Row can contain only one select menu and cannot contain buttons if it has a select menu. + +###### User Select Structure + +| Field | Type | Description | +|-----------------|---------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------| +| type | integer | `5` for user select | +| id? | integer | Optional identifier for component | +| custom_id | string | ID for the select menu; max 100 characters | +| placeholder? | string | Placeholder text if nothing is selected; max 150 characters | +| default_values? | array of [default value objects](/docs/components/reference#user-select-select-default-value-structure) | List of default values for auto-populated select menu components; number of default values must be in the range defined by `min_values` and `max_values` | +| min_values? | integer | Minimum number of items that must be chosen (defaults to 1); min 0, max 25 | +| max_values? | integer | Maximum number of items that can be chosen (defaults to 1); max 25 | +| disabled? | boolean | Whether select menu is disabled (defaults to `false`) | + +###### Select Default Value Structure + +| Field | Type | Description | +|-------|-----------|-------------------------------------------------------------------------------| +| id | snowflake | ID of a user, role, or channel | +| type | string | Type of value that `id` represents. Either `"user"`, `"role"`, or `"channel"` | + +###### Example + +```json +"components": [ + { + "type": 1, + "components": [ + { + "type": 5, + "custom_id": "user_select", + "placeholder": "Select a user" + } + ] + } +] +``` + +![Example of a User Select with two people and an app in a server](images/components/user-select.png) + +###### User Select Interaction + +Check out the [String Select interaction](/docs/components/reference#string-select-string-select-interaction) to see the structure of the Select interaction object and resolved object. + +## Role Select + +A Role Select is an interactive component that allows users to select one or more roles in a message. Options are automatically populated based on the server's available roles. + +Role Selects can be configured for both single-select and multi-select behavior. When a user finishes making their choice(s) your app receives an [interaction](/docs/interactions/receiving-and-responding#interaction-object-interaction-structure). + +Role Selects must be placed inside an [Action Row](/docs/components/reference#action-row) and are only available in messages. An Action Row can contain only one select menu and cannot contain buttons if it has a select menu. + +###### Role Select Structure + +| Field | Type | Description | +|-----------------|---------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------| +| type | integer | `6` for role select | +| id? | integer | Optional identifier for component | +| custom_id | string | ID for the select menu; max 100 characters | +| placeholder? | string | Placeholder text if nothing is selected; max 150 characters | +| default_values? | array of [default value objects](/docs/components/reference#user-select-select-default-value-structure) | List of default values for auto-populated select menu components; number of default values must be in the range defined by `min_values` and `max_values` | +| min_values? | integer | Minimum number of items that must be chosen (defaults to 1); min 0, max 25 | +| max_values? | integer | Maximum number of items that can be chosen (defaults to 1); max 25 | +| disabled? | boolean | Whether select menu is disabled (defaults to `false`) | + +###### Example + +```json +"components": [ + { + "type": 1, + "components": [ + { + "type": 6, + "custom_id": "role_select", + "placeholder": "Which roles?", + "min_values": 1, + "max_values": 3 + } + ] + } +] +``` + +![Example of a Role Select allowing up to 3 choices](images/components/role-select.png) + +###### Role Select Interaction + +Check out the [String Select interaction](/docs/components/reference#string-select-string-select-interaction) to see the structure of the Select interaction object and resolved object. + +## Mentionable Select + +A Mentionable Select is an interactive component that allows users to select one or more mentionables in a message. Options are automatically populated based on available mentionables in the server. + +Mentionable Selects can be configured for both single-select and multi-select behavior. When a user finishes making their choice(s), your app receives an [interaction](/docs/interactions/receiving-and-responding#interaction-object-interaction-structure). + +Mentionable Selects must be placed inside an [Action Row](/docs/components/reference#action-row) and are only available in messages. An Action Row can contain only one select menu and cannot contain buttons if it has a select menu. + +###### Mentionable Select Structure + +| Field | Type | Description | +|-----------------|---------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------| +| type | integer | `7` for mentionable select | +| id? | integer | Optional identifier for component | +| custom_id | string | ID for the select menu; max 100 characters | +| placeholder? | string | Placeholder text if nothing is selected; max 150 characters | +| default_values? | array of [default value objects](/docs/components/reference#user-select-select-default-value-structure) | List of default values for auto-populated select menu components; number of default values must be in the range defined by `min_values` and `max_values` | +| min_values? | integer | Minimum number of items that must be chosen (defaults to 1); min 0, max 25 | +| max_values? | integer | Maximum number of items that can be chosen (defaults to 1); max 25 | +| disabled? | boolean | Whether select menu is disabled (defaults to `false`) | + +###### Example + +```json +"components": [ + { + "type": 1, + "components": [ + { + "type": 7, + "custom_id": "mentionable_select", + "placeholder": "Who?" + } + ] + } +] +``` + +![Example of a Mentionable Select](images/components/mentionable-select.png) + +###### Mentionable Select Interaction + +Check out the [String Select interaction](/docs/components/reference#string-select-string-select-interaction) to see the structure of the Select interaction object and resolved object. + +## Channel Select + +A Channel Select is an interactive component that allows users to select one or more channels in a message. Options are automatically populated based on available channels in the server and can be filtered by channel types. + +Channel Selects can be configured for both single-select and multi-select behavior. When a user finishes making their choice(s) your app receives an [interaction](/docs/interactions/receiving-and-responding#interaction-object-interaction-structure). + +Channel Selects must be placed inside an [Action Row](/docs/components/reference#action-row) and are only available in messages. An Action Row can contain only one select menu and cannot contain buttons if it has a select menu. + +###### Channel Select Structure + +| Field | Type | Description | +|-----------------|---------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------| +| type | integer | `8` for channel select | +| id? | integer | Optional identifier for component | +| custom_id | string | ID for the select menu; max 100 characters | +| channel_types? | array of [channel types](/docs/resources/channel#channel-object-channel-types) | List of channel types to include in the channel select component | +| placeholder? | string | Placeholder text if nothing is selected; max 150 characters | +| default_values? | array of [default value objects](/docs/components/reference#user-select-select-default-value-structure) | List of default values for auto-populated select menu components; number of default values must be in the range defined by `min_values` and `max_values` | +| min_values? | integer | Minimum number of items that must be chosen (defaults to 1); min 0, max 25 | +| max_values? | integer | Maximum number of items that can be chosen (defaults to 1); max 25 | +| disabled? | boolean | Whether select menu is disabled (defaults to `false`) | + +###### Example + +```json +"components": [ + { + "type": 1, + "components": [ + { + "type": 8, + "custom_id": "channel_select", + "channel_types": [0], + "placeholder": "Which text channel?" + } + ] + } +] +``` + +![Example of a Channel Select for text channels](images/components/channel-select.png) + +###### Channel Select Interaction + +Check out the [String Select interaction](/docs/components/reference#string-select-string-select-interaction) to see the structure of the Select interaction object and resolved object. + +## Section + +A Section is a top-level layout component that allows you to join text contextually with an accessory. + +Sections are only available in messages. + +:::info +To use this component, you need to send the [message flag](/docs/resources/message#message-object-message-flags) `1 << 15` (IS_COMPONENTS_V2) which can be activated on a per-message basis. +::: + +###### Section Structure + +| Field | Type | Description | +|------------|-----------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------| +| type | integer | `9` for section component | +| id? | integer | Optional identifier for component | +| components | array of [text display components](/docs/components/reference#text-display) | One to three text components | +| accessory | [thumbnail component](/docs/components/reference#thumbnail) or [button components](/docs/components/reference#button) | A thumbnail or a button component, with a future possibility of adding more compatible components | + +:::info +Don't hardcode `components` to contain only text components. We may add other components in the future. Similarly, `accessory` may be expanded to include other components in the future. +::: + +###### Example + +```json +"components": [ + { + "type": 9, + "components": [ + { + "type": 10, + "content": "# Real Game v7.3" + }, + { + "type": 10, + "content": "Hope you're excited, the update is finally here! Here are some of the changes:\n- Fixed a bug where certain treasure chests wouldn't open properly\n- Improved server stability during peak hours\n- Added a new type of gravity that will randomly apply when the moon is visible in-game\n- Every third thursday the furniture will scream your darkest secrets to nearby npcs" + }, + { + "type": 10, + "content": "-# That last one wasn't real, but don't use voice chat near furniture just in case..." + } + ], + "accessory": { + "type": 11, + "media": { + "url": "https://websitewithopensourceimages/gamepreview.png" + } + } + } +] +``` + +![Example of a Section showing a fake game changelog and a thumbnail](images/components/section.png) + +## Text Display + +A Text Display is a top-level content component that allows you to add text to your message formatted with markdown and mention users and roles. This is similar to the `content` field of a message, but allows you to add multiple text components, controlling the layout of your message. + +Text Displays are only available in messages. + +:::info +To use this component, you need to send the [message flag](/docs/resources/message#message-object-message-flags) `1 << 15` (IS_COMPONENTS_V2) which can be activated on a per-message basis. +::: + +###### Text Display Structure + +| Field | Type | Description | +|---------|---------|--------------------------------------------------| +| type | integer | `10` for text display | +| id? | integer | Optional identifier for component | +| content | string | Text that will be displayed similar to a message | +Th +###### Example + +```json +"components": [ + { + "type": 10, + "content": "# This is a Text Display\nAll the regular markdown rules apply\n- You can make lists\n- You can use `code blocks`\n- You can use [links](http://watchanimeattheoffice.com/)\n- Even :blush: :star_struck: :exploding_head:\n- Spolier alert: ||these too!||" + } +] +``` + +![Example of a Text Display with markdown](images/components/text-display.png) + +## Thumbnail + +A Thumbnail is a content component that is a small image only usable as an accessory in a [section](/docs/components/reference#section). The preview comes from an url or attachment through the [unfurled media item](/docs/components/reference#unfurled-media-item-structure) structure. + +Thumbnails are only available in messages as an accessory in a [section](/docs/components/reference#section). + +:::info +To use this component, you need to send the [message flag](/docs/resources/message#message-object-message-flags) `1 << 15` (IS_COMPONENTS_V2), which can be activated on a per-message basis. +::: + +###### Thumbnail Structure + +| Field | Type | Description | +|--------------|---------------------------------------------------------------------------------|---------------------------------------------------------------------------------| +| type | integer | `11` for thumbnail component | +| id? | integer | Optional identifier for component | +| media | [unfurled media item](/docs/components/reference#unfurled-media-item-structure) | A url or attachment | +| description? | string | Alt text for the media | +| spoiler? | boolean | Whether the thumbnail should be a spoiler (or blurred out). Defaults to `false` | + +###### Example + +Check out the [Section example](/docs/components/reference#section-example) to see the thumbnail in use as an accessory. + +## Media Gallery + +A Media Gallery is a top-level content component that allows you to display 1-10 media attachments in an organized gallery format. Each item can have optional descriptions and can be marked as spoilers. + +Media Galleries are only available in messages. + +:::info +To use this component, you need to send the [message flag](/docs/resources/message#message-object-message-flags) `1 << 15` (IS_COMPONENTS_V2) which can be activated on a per-message basis. +::: + +###### Media Gallery Structure + +| Field | Type | Description | +|-------|-------------------------------------------------------------------------------------------------------|-----------------------------------| +| type | integer | `12` for media gallery component | +| id? | integer | Optional identifier for component | +| items | array of [media gallery items](/docs/components/reference#media-gallery-media-gallery-item-structure) | 1 to 10 media gallery items | + +###### Media Gallery Item Structure + +| Field | Type | Description | +|--------------|---------------------------------------------------------------------------------|-----------------------------------------------------------------------------| +| media | [unfurled media item](/docs/components/reference#unfurled-media-item-structure) | A url or attachment | +| description? | string | Alt text for the media | +| spoiler? | boolean | Whether the media should be a spoiler (or blurred out). Defaults to `false` | + +###### Example + +```json +"components": [ + { + "type": 10, + "content": "Live webcam shots as of 18-04-2025 at 12:00 UTC" + }, + { + "type": 12, + "items": [ + { + "media": {"url": "https://livevideofeedconvertedtoimage/webcam1.png"}, + "description": "An aerial view looking down on older industrial complex buildings. The main building is white with many windows and pipes running up the walls." + }, + { + "media": {"url": "https://livevideofeedconvertedtoimage/webcam2.png"}, + "description": "An aerial view of old broken buildings. Nature has begun to take root in the rooftops. A portion of the middle building's roof has collapsed inward. In the distant haze you can make out a far away city." + }, + { + "media": {"url": "https://livevideofeedconvertedtoimage/webcam3.png"}, + "description": "A street view of a downtown city. Prominently in photo are skyscrapers and a domed building" + } + ] + } +] +``` + +![Example of a Media Gallery showing screenshots from live webcam feeds](images/components/media-gallery.png) + +## File + +A File is a top-level component that allows you to display an [uploaded file](/docs/components/reference#uploading-a-file) as an attachment to the message and reference it in the component. Each file component can only display 1 attached file, but you can upload multiple files and add them to different file components within your payload. This is similar to the `embeds` field of a message but allows you to control the layout of your message by using this anywhere as a component. Files are only available in messages. + +:::info +To use this component, you need to send the [message flag](/docs/resources/message#message-object-message-flags) `1 << 15` (IS_COMPONENTS_V2) which can be activated on a per-message basis. +::: + +###### File Structure + +| Field | Type | Description | +|----------|---------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------| +| type | integer | `13` for a file component | +| id? | integer | Optional identifier for component | +| file | [unfurled media item](/docs/components/reference#unfurled-media-item-structure) | This unfurled media item is unique in that it **only** support attachment references using the `attachment://` syntax | +| spoiler? | boolean | Whether the media should be a spoiler (or blurred out). Defaults to `false` | + +###### Example + +```json +"components": [ + { + "type": 10, + "content": "# New game version released for testing!" + }, + { + "type": 10, + "content": "Grab the game here:" + }, + { + "type": 13, + "file": { + "url": "attachment://game.zip" + } + }, + { + "type": 10, + "content": "Latest manual artwork here:" + }, + { + "type": 13, + "file": { + "url": "attachment://manual.pdf" + } + } +] +``` + +![Example of a File showing a download for a game and manual](images/components/file.png) + +## Separator + +A Separator is a top-level layout component that adds vertical padding and visual division between other components. + +Separators are only available in messages. + +:::info +To use this component, you need to send the [message flag](/docs/resources/message#message-object-message-flags) `1 << 15` (IS_COMPONENTS_V2) which can be activated on a per-message basis. +::: + +###### Separator Structure + +| Field | Type | Description | +|----------|---------|-----------------------------------------------------------------------------------------| +| type | integer | `14` for separator component | +| id? | integer | Optional identifier for component | +| divider? | boolean | Whether a visual divider should be displayed in the component. Defaults to `true` | +| spacing? | integer | Size of separator padding—`1` for small padding, `2` for large padding. Defaults to `1` | + +###### Example + +```json +"components": [ + { + "type": 10, + "content": "It's dangerous to go alone!" + }, + { + "type": 14, + "divider": true, + "spacing": 1 + }, + { + "type": 10, + "content": "Take this." + } +] +``` + +![Example of a separator with large spacing dividing content](images/components/separator.png) + +## Container + +A Container is a top-level layout component that holds up to 10 components. Containers are visually distinct from surrounding components and has an optional customizable color bar. + +Containers are only available in messages. + +:::info +To use this component, you need to send the [message flag](/docs/resources/message#message-object-message-flags) `1 << 15` (IS_COMPONENTS_V2) which can be activated on a per-message basis. +::: + +###### Container Structure + +| Field | Type | Description | +|---------------|---------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| type | integer | `17` for container component | +| id? | integer | Optional identifier for component | +| components | array of components | Up to 10 components of the type [action row](/docs/components/reference#action-row), [text display](/docs/components/reference#text-display), [section](/docs/components/reference#section), [media gallery](/docs/components/reference#media-gallery), [separator](/docs/components/reference#separator), or [file](/docs/components/reference#file) | +| accent_color? | ?integer | Color for the accent on the container as RGB from `0x000000` to `0xFFFFFF` | +| spoiler? | boolean | Whether the container should be a spoiler (or blurred out). Defaults to `false`. | + +###### Example + +```json +"components": [ + { + "type": 17, + "accent_color": 703487, + "components": [ + { + "type": 10, + "content": "# You have encountered a wild coyote!" + }, + { + "type": 12, + "items": [ + { + "media": {"url": "https://websitewithopensourceimages/coyote.png"}, + } + ] + }, + { + "type": 10, + "content": "What would you like to do?" + }, + { + "type": 1, + "components": [ + { + "type": 2, + "custom_id": "pet_coyote", + "label": "Pet it!", + "style": 1 + }, + { + "type": 2, + "custom_id": "feed_coyote", + "label": "Attempt to feed it", + "style": 2 + }, + { + "type": 2, + "custom_id": "run_away", + "label": "Run away!", + "style": 4 + } + ] + } + ] + } +] +``` + +![Example of a container showing text, image, and buttons for a wild enemy encounter](images/components/container.png) + +## Unfurled Media Item Structure + +| Field | Type | Description | +|---------------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------| +| url | string | Supports arbitrary urls and `attachment://` references | +| proxy_url? | string | The proxied url of the media item. This field is ignored and provided by the API as part of the response | +| height? | ?integer | The height of the media item. This field is ignored and provided by the API as part of the response | +| width? | ?integer | The width of the media item. This field is ignored and provided by the API as part of the response | +| content_type? | string | The [media type](https://en.wikipedia.org/wiki/Media_type) of the content. This field is ignored and provided by the API as part of the response | + +### Uploading a file + +To upload a file with your message, you'll need to send your payload as `multipart/form-data` (rather than `application/json`) and include your file with a valid filename in your payload. Details and examples for uploading files can be found in the [API Reference](/docs/reference#uploading-files). + +## Legacy Message Component Behavior + +Before the introduction of the `IS_COMPONENTS_V2` flag ([see changelog](/docs/change-log/2025-04-22-components-v2)), message components were sent in conjunction with message content. This means that you could send a message using a subset of the available components without setting the `IS_COMPONENTS_V2` flag, and the components would be included in the message content along with `content` and `embeds`. + +Apps using this Legacy Message Component behavior will continue to work as expected, but it is recommended to use the new `IS_COMPONENTS_V2` flag for new apps or features as they offer more options for layout and customization. + +Legacy Message Component Example + +```json +{ + "content": "This is a message with legacy components", + "components": [ + { + "type": 1, + "components": [ + { + "type": 2, + "style": 1, + "label": "Click Me", + "custom_id": "click_me_1" + } + ] + } + ] +} +``` \ No newline at end of file diff --git a/docs/components/using-message-components.mdx b/docs/components/using-message-components.mdx new file mode 100644 index 0000000000..6cf26fc671 --- /dev/null +++ b/docs/components/using-message-components.mdx @@ -0,0 +1,106 @@ +--- +sidebar_label: Using Message Components +--- + +# Using Message Components + +## Overview + +Message components are a powerful way to add interactivity to your messages. They allow you to create rich, interactive experiences for your users, making it easier for them to engage with your content. + +:::info +If you are sending components as part of a [webhook](/docs/resources/webhook) you'll need to use the [`?with_components=true`](/docs/resources/webhook#execute-webhook-query-string-params) query param otherwise they'll be ignored. +::: + +### Prerequisites + +- You must have a Discord account and be a member of the Discord Developer Portal. +- You must have a Discord application created in the Discord Developer Portal. +- You must have the necessary permissions to send messages in the channel where you want to use components. + +--- + +## Sending a Message with a Component + +To send a message with a component, you need to set the `IS_COMPONENTS_V2` flag (`1<<15`) in your message's `flags` field. This can be done when using [Message Create](/docs/resources/message#create-message), [Execute Webhook](/docs/resources/webhook#execute-webhook), or [responding to an interaction](/docs/interactions/receiving-and-responding#create-followup-message). + +This flag indicates that the message contains components and disables traditional content and embeds. + +All content must be sent as components instead of using the standard message format. + +```json +{ + "flags": "32768", + "components": [ + { + "type": 10, + "content": "This is a message using the Text Display component" + }, + ] +} +``` + +## Sending a Message with Multiple Components + +To send a message with multiple components, you can include multiple component objects in your message's `components` field. This field allows you to specify an array of components that will be included in the message. + +```json +{ + "flags": "32768", + "components": [ + { + "type": 10, + "content": "This is a Text Display component." + }, + { + "type": 10, + "content": "This is another Text Display component!" + }, + ] +} +``` + +## Nesting Components with Layout Components + +You can also nest components within layout components. This gives you more flexibility in displaying information, images, and interactive components to your users. Check out the [list of components](/docs/components/reference#component-object-component-types) for a complete list of available layout components. + +For example, you can create a message with an Action Row component that contains multiple Button components. + +```json +{ + "flags": "32768", + "components": [ + { + "type": 10, + "content": "This is a message with v2 components" + }, + { + "type": 1, + "components": [ + { + "type": 2, + "style": 1, + "label": "Click Me", + "custom_id": "click_me_1" + }, + { + "type": 2, + "style": 2, + "label": "Click Me Too", + "custom_id": "click_me_2" + } + ] + } + ] +} +``` + +## Using Message Components with Interactions + +When a user interacts with an interactive message component, your app will [receive an interaction event](/docs/interactions/overview). This event contains information about the interaction, including the type of interaction and the component that was interacted with. + +See the [list of supported component types](/docs/components/reference#component-object-component-types) for a list of interactive message components and their interaction event payloads. + +You can use this information to respond to the interaction, update the message, or perform other actions, such as displaying a modal based on the user's input. + +Check out the [Interactions documentation](/docs/interactions/overview) for more information on handling interactions and responding to user input from interactive components. \ No newline at end of file diff --git a/docs/components/using-modal-components.mdx b/docs/components/using-modal-components.mdx new file mode 100644 index 0000000000..52c65f7c7d --- /dev/null +++ b/docs/components/using-modal-components.mdx @@ -0,0 +1,70 @@ +--- +sidebar_label: Using Modal Components +--- + +# Using Modal Components + +## Overview + +Modal components are a great way to collect freeform information from your users. + +:::info +Currently, only [Text Input](/docs/components/reference#text-input) fields are supported in a modal, and each one must be placed in an [Action Row](/docs/components/reference#action-row). +::: + +### Prerequisites + +- You must have a Discord account and be a member of the Discord Developer Portal. +- You must have a Discord application created in the Discord Developer Portal. + +--- + +## Displaying a Modal + +Displaying a modal can be done in response to a [slash command](https://discord.com/developers/docs/tutorials/upgrading-to-application-commands#slash-commands) or when responding to an [interaction](/docs/interactions/receiving-and-responding). When displaying a modal you'll use an [interaction response](/docs/interactions/receiving-and-responding#interaction-response-object) with the [`MODAL`](/docs/interactions/receiving-and-responding#interaction-response-object-interaction-callback-type) interaction callback type and [modal fields](/docs/interactions/receiving-and-responding#interaction-response-object-modal). + +An example of a modal with two Text Inputs: + +```json +{ + "type": 9, + "data": { + "custom_id": "feedback_modal", + "title": "Submit Feedback", + "components": [ + { + "type": 1, + "components": [ + { + "type": 4, + "custom_id": "feedback_subject", + "label": "Subject", + "style": 1, + "min_length": 1, + "max_length": 100, + "placeholder": "What is your feedback about?", + "required": true + } + ] + }, + { + "type": 1, + "components": [ + { + "type": 4, + "custom_id": "feedback_details", + "label": "Details", + "style": 2, + "min_length": 10, + "max_length": 1000, + "placeholder": "Please provide details...", + "required": true + } + ] + } + ] + } +} +``` + +![Example of a modal with two text inputs one for subject and one for details](images/components/modal.png) \ No newline at end of file diff --git a/docs/developer-tools/community-resources.mdx b/docs/developer-tools/community-resources.mdx index 4990bea2aa..187449bdae 100644 --- a/docs/developer-tools/community-resources.mdx +++ b/docs/developer-tools/community-resources.mdx @@ -37,7 +37,7 @@ Discord does not maintain official SDKs. The following table is an inexhaustive ## Interactions -[Interactions](/docs/interactions/receiving-and-responding#) are the great, new way of making a Discord bot. The following open-source libraries provide help for the security and authentication checks that are mandatory if you are receiving Interactions via outgoing webhook. They also include some types for the Interactions data models. +[Interactions](/docs/interactions/receiving-and-responding) are the great, new way of making a Discord bot. The following open-source libraries provide help for the security and authentication checks that are mandatory if you are receiving Interactions via outgoing webhook. They also include some types for the Interactions data models. - C# - [Discord.Net.Rest](https://github.com/discord-net/Discord.Net) diff --git a/docs/events/gateway-events.mdx b/docs/events/gateway-events.mdx index c0754b47d3..d46320ede7 100644 --- a/docs/events/gateway-events.mdx +++ b/docs/events/gateway-events.mdx @@ -354,7 +354,7 @@ Receive events are Gateway events encapsulated in an [event payload](/docs/event | [Integration Create](/docs/events/gateway-events#integration-create) | Guild integration was created | | [Integration Update](/docs/events/gateway-events#integration-update) | Guild integration was updated | | [Integration Delete](/docs/events/gateway-events#integration-delete) | Guild integration was deleted | -| [Interaction Create](/docs/events/gateway-events#interaction-create) | User used an interaction, such as an [Application Command](/docs/interactions/application-commands#) | +| [Interaction Create](/docs/events/gateway-events#interaction-create) | User used an interaction, such as an [Application Command](/docs/interactions/application-commands) | | [Invite Create](/docs/events/gateway-events#invite-create) | Invite to a channel was created | | [Invite Delete](/docs/events/gateway-events#invite-delete) | Invite to a channel was deleted | | [Message Create](/docs/events/gateway-events#message-create) | Message was created | @@ -1384,7 +1384,7 @@ Sent when a guild channel's webhook is created, updated, or deleted. #### Interaction Create -Sent when a user uses an [Application Command](/docs/interactions/application-commands#) or [Message Component](/docs/interactions/message-components). Inner payload is an [Interaction](/docs/interactions/receiving-and-responding#interaction-object-interaction-structure). +Sent when a user uses an [Application Command](/docs/interactions/application-commands) or [Message Component](/docs/components/reference#component-object). Inner payload is an [Interaction](/docs/interactions/receiving-and-responding#interaction-object-interaction-structure). ### Stage Instances diff --git a/docs/interactions/application-commands.mdx b/docs/interactions/application-commands.mdx index 5bc8732734..fa81d64484 100644 --- a/docs/interactions/application-commands.mdx +++ b/docs/interactions/application-commands.mdx @@ -121,7 +121,7 @@ Details about Entry Point command handler types are in the [Entry Point handlers ## Authorizing Your Application -Application commands do not depend on a bot user in the guild; they use the [interactions](/docs/interactions/receiving-and-responding#) model. To create commands in a guild, your app must be authorized with the `applications.commands` scope which can be used independently, but is also automatically included with the `bot` scope. +Application commands do not depend on a bot user in the guild; they use the [interactions](/docs/interactions/receiving-and-responding) model. To create commands in a guild, your app must be authorized with the `applications.commands` scope which can be used independently, but is also automatically included with the `bot` scope. When requesting this scope, we "shortcut" the OAuth2 flow similar to adding a bot. You don't need to complete the flow, exchange for a token, or any of that. diff --git a/docs/interactions/message-components.md b/docs/interactions/message-components.md deleted file mode 100644 index 87600e4074..0000000000 --- a/docs/interactions/message-components.md +++ /dev/null @@ -1,621 +0,0 @@ -# Message Components - -Message components—we'll call them "components" moving forward—are a framework for adding interactive elements to the messages your app or bot sends. They're accessible, customizable, and easy to use. - -There are several different types of components; this documentation will outline the basics of this new framework and each example. - -## What is a Component - -Components are a field on the [message object](/docs/resources/message#message-object), so you can use them whether you're sending messages or responding to a [slash command](/docs/interactions/application-commands#) or other interaction. - -### Component Object - -###### Component Types - -| Type | Name | Description | -|------|--------------------|---------------------------------------------------| -| 1 | Action Row | Container for other components | -| 2 | Button | Button object | -| 3 | String Select | Select menu for picking from defined text options | -| 4 | Text Input | Text input object | -| 5 | User Select | Select menu for users | -| 6 | Role Select | Select menu for roles | -| 7 | Mentionable Select | Select menu for mentionables (users *and* roles) | -| 8 | Channel Select | Select menu for channels | - -The structure of each component type is described in detail below. - -###### Example Component - -```json -{ - "content": "This is a message with components", - "components": [ - { - "type": 1, - "components": [] - } - ] -} -``` - -## Action Rows - -An Action Row is a non-interactive container component for other types of components. It has a `type: 1` and a sub-array of `components` of other types. - -- You can have up to 5 Action Rows per message -- An Action Row cannot contain another Action Row - -```json -{ - "content": "This is a message with components", - "components": [ - { - "type": 1, - "components": [ - { - "type": 2, - "label": "Click me!", - "style": 1, - "custom_id": "click_one" - } - ] - - } - ] -} -``` - -## Responding to a Component Interaction - -Responding to a user interacting with a component is the same as other interaction types, like application commands. You can simply ACK the request, send a followup message, or edit the original message to something new. Check out [Responding to An Interaction](/docs/interactions/receiving-and-responding#responding-to-an-interaction) and [interaction response](/docs/interactions/receiving-and-responding#interaction-response-object) for more. - -## Custom ID - -Components, aside from Action Rows, must have a `custom_id` field. This field is defined by the developer when sending the component payload, and is returned in the interaction payload sent when a user interacts with the component. For example, if you set `custom_id: click_me` on a button, you'll receive an interaction containing `custom_id: click_me` when a user clicks that button. - -`custom_id` must be unique per component; multiple buttons on the same message must not share the same `custom_id`. This field is a string of max 100 characters, and can be used flexibly to maintain state or pass through other important data. - -## Buttons - -Buttons are interactive components that render in messages. They can be clicked by users, and send an [interaction](/docs/interactions/receiving-and-responding#interaction-object) to your app when clicked. - -- Buttons must be sent inside an Action Row -- An Action Row can contain up to 5 buttons -- An Action Row containing buttons cannot also contain any select menu components - -### Button Object - -###### 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 | -| sku_id? | snowflake | Identifier for a purchasable [SKU](/docs/resources/sku#sku-object), only available when using premium-style buttons | -| 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 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 - -| Name | Value | Color | Required Field | -|-----------|-------|--------------------------|----------------| -| Primary | 1 | blurple | `custom_id` | -| Secondary | 2 | grey | `custom_id` | -| Success | 3 | green | `custom_id` | -| Danger | 4 | red | `custom_id` | -| Link | 5 | grey, navigates to a URL | `url` | -| Premium | 6 | blurple | `sku_id` | - -![An image showing the different button styles](images/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](images/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](images/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](images/premium-button.png) - -### Component Interaction Object - -###### Sample Component Interaction - -```json -{ - "version": 1, - "type": 3, - "token": "unique_interaction_token", - "message": { - "type": 0, - "tts": false, - "timestamp": "2021-05-19T02:12:51.710000+00:00", - "pinned": false, - "mentions": [], - "mention_roles": [], - "mention_everyone": false, - "id": "844397162624450620", - "flags": 0, - "embeds": [], - "edited_timestamp": null, - "content": "This is a message with components.", - "components": [ - { - "type": 1, - "components": [ - { - "type": 2, - "label": "Click me!", - "style": 1, - "custom_id": "click_one" - } - ] - } - ], - "channel_id": "345626669114982402", - "author": { - "username": "Mason", - "public_flags": 131141, - "id": "53908232506183680", - "discriminator": "1337", - "avatar": "a_d5efa99b3eeaa7dd43acca82f5692432" - }, - "attachments": [] - }, - "member": { - "user": { - "username": "Mason", - "public_flags": 131141, - "id": "53908232506183680", - "discriminator": "1337", - "avatar": "a_d5efa99b3eeaa7dd43acca82f5692432" - }, - "roles": [ - "290926798626357999" - ], - "premium_since": null, - "permissions": "17179869183", - "pending": false, - "nick": null, - "mute": false, - "joined_at": "2017-03-13T19:19:14.040000+00:00", - "is_pending": false, - "deaf": false, - "avatar": null - }, - "id": "846462639134605312", - "guild_id": "290926798626357999", - "data": { - "custom_id": "click_one", - "component_type": 2 - }, - "channel_id": "345626669114982999", - "application_id": "290926444748734465" -} -``` - -## Select Menus - -Select menus are interactive components that allow users to select one or more options from a dropdown list in messages. On desktop, clicking on a select menu opens a dropdown-style UI; on mobile, tapping a select menu opens up a half-sheet with the options. - -![A role select component on desktop](images/desktop-role-select-menu.png) - -Select menus support single-select and multi-select behavior, meaning you can prompt a user to choose just one item from a list, or multiple. When a user finishes making their choice(s) by clicking out of the dropdown or closing the half-sheet, your app will receive an [interaction](/docs/interactions/receiving-and-responding#interaction-object-interaction-structure). - -- Select menus must be sent inside an Action Row -- An Action Row can contain only one select menu -- An Action Row containing a select menu cannot also contain buttons - -### Select Menu Types - -There are 5 different [select menu components](/docs/interactions/message-components#component-object-component-types) that can be included in Action Rows. - -The string select menu (type `3`) is the *only* select type that allows (and *requires*) apps to define the `options` that appear in the dropdown list. The other 4 select menu components (users, roles, mentionables, and channels) are auto-populated with options corresponding to the resource type—similar to [command option types](/docs/interactions/application-commands#application-command-object-application-command-option-type). - -In addition to the `values` array in all [select menu interaction payloads](/docs/interactions/message-components#select-menu-object-select-menu-interaction), auto-populated select menu components (user, role, mentionable, and channel) also include an additional [`resolved` object](/docs/interactions/message-components#select-menu-object-select-menu-resolved-object) that provides additional details about the user's selected resource. - -The payloads for the select menu components are detailed in the [select menu structure](/docs/interactions/message-components#select-menu-object-select-menu-structure). - -###### Select Menu Example - -```json -// This is a message -{ - "content": "Mason is looking for new arena partners. What classes do you play?", - "components": [ - { - "type": 1, - "components": [ - { - "type": 3, - "custom_id": "class_select_1", - "options":[ - { - "label": "Rogue", - "value": "rogue", - "description": "Sneak n stab", - "emoji": { - "name": "rogue", - "id": "625891304148303894" - } - }, - { - "label": "Mage", - "value": "mage", - "description": "Turn 'em into a sheep", - "emoji": { - "name": "mage", - "id": "625891304081063986" - } - }, - { - "label": "Priest", - "value": "priest", - "description": "You get heals when I'm done doing damage", - "emoji": { - "name": "priest", - "id": "625891303795982337" - } - } - ], - "placeholder": "Choose a class", - "min_values": 1, - "max_values": 3 - } - ] - } - ] -} -``` - -### Select Menu Object - -###### Select Menu Structure - -| Field | Type | Description | -|-----------------------|---------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| type | integer | [Type](/docs/interactions/message-components#component-object-component-types) of select menu component (text: `3`, user: `5`, role: `6`, mentionable: `7`, channels: `8`) | -| custom_id | string | ID for the select menu; max 100 characters | -| options?\* | array of [select options](/docs/interactions/message-components#select-menu-object-select-option-structure) | Specified choices in a select menu (only required and available for string selects (type `3`); max 25 | -| channel_types?\*\* | array of [channel types](/docs/resources/channel#channel-object-channel-types) | List of channel types to include in the channel select component (type `8`) | -| placeholder? | string | Placeholder text if nothing is selected; max 150 characters | -| default_values?\*\*\* | array of [default value objects](/docs/interactions/message-components#select-menu-object-select-default-value-structure) | List of default values for auto-populated select menu components; number of default values must be in the range defined by `min_values` and `max_values` | -| min_values? | integer | Minimum number of items that must be chosen (defaults to 1); min 0, max 25 | -| max_values? | integer | Maximum number of items that can be chosen (defaults to 1); max 25 | -| disabled? | boolean | Whether select menu is disabled (defaults to `false`) | - -\* `options` is required for string select menus (component type `3`), and unavailable for all other select menu components. - -\*\* `channel_types` can only be used for channel select menu components. - -\*\*\* `default_values` is only available for auto-populated select menu components, which include user (`5`), role (`6`), mentionable (`7`), and channel (`8`) [components](/docs/interactions/message-components#component-object-component-types). - -###### Select Option Structure - -| Field | Type | Description | -|--------------|------------------------------------------------------------|----------------------------------------------------------| -| label | string | User-facing name of the option; max 100 characters | -| value | string | Dev-defined value of the option; max 100 characters | -| description? | string | Additional description of the option; max 100 characters | -| emoji? | partial [emoji](/docs/resources/emoji#emoji-object) object | `id`, `name`, and `animated` | -| default? | boolean | Will show this option as selected by default | - -###### Select Default Value Structure - -| Field | Type | Description | -|-------|-----------|-------------------------------------------------------------------------------| -| id | snowflake | ID of a user, role, or channel | -| type | string | Type of value that `id` represents. Either `"user"`, `"role"`, or `"channel"` | - -###### Select Menu Interaction - -```json -{ - "application_id": "845027738276462632", - "channel_id": "772908445358620702", - "data": { - "component_type":3, - "custom_id": "class_select_1", - "values": [ - "mage", - "rogue" - ] - }, - "guild_id": "772904309264089089", - "id": "847587388497854464", - "member": { - "avatar": null, - "deaf": false, - "is_pending": false, - "joined_at": "2020-11-02T19:25:47.248000+00:00", - "mute": false, - "nick": "Bot Man", - "pending": false, - "permissions": "17179869183", - "premium_since": null, - "roles": [ - "785609923542777878" - ], - "user":{ - "avatar": "a_d5efa99b3eeaa7dd43acca82f5692432", - "discriminator": "1337", - "id": "53908232506183680", - "public_flags": 131141, - "username": "Mason" - } - }, - "message":{ - "application_id": "845027738276462632", - "attachments": [], - "author": { - "avatar": null, - "bot": true, - "discriminator": "5284", - "id": "845027738276462632", - "public_flags": 0, - "username": "Interactions Test" - }, - "channel_id": "772908445358620702", - "components": [ - { - "components": [ - { - "custom_id": "class_select_1", - "max_values": 1, - "min_values": 1, - "options": [ - { - "description": "Sneak n stab", - "emoji":{ - "id": "625891304148303894", - "name": "rogue" - }, - "label": "Rogue", - "value": "rogue" - }, - { - "description": "Turn 'em into a sheep", - "emoji":{ - "id": "625891304081063986", - "name": "mage" - }, - "label": "Mage", - "value": "mage" - }, - { - "description": "You get heals when I'm done doing damage", - "emoji":{ - "id": "625891303795982337", - "name": "priest" - }, - "label": "Priest", - "value": "priest" - } - ], - "placeholder": "Choose a class", - "type": 3 - } - ], - "type": 1 - } - ], - "content": "Mason is looking for new arena partners. What classes do you play?", - "edited_timestamp": null, - "embeds": [], - "flags": 0, - "id": "847587334500646933", - "interaction": { - "id": "847587333942935632", - "name": "dropdown", - "type": 2, - "user": { - "avatar": "a_d5efa99b3eeaa7dd43acca82f5692432", - "discriminator": "1337", - "id": "53908232506183680", - "public_flags": 131141, - "username": "Mason" - } - }, - "mention_everyone": false, - "mention_roles":[], - "mentions":[], - "pinned": false, - "timestamp": "2021-05-27T21:29:27.956000+00:00", - "tts": false, - "type": 20, - "webhook_id": "845027738276462632" - }, - "token": "UNIQUE_TOKEN", - "type": 3, - "version": 1 -} -``` - -###### Select Menu Resolved Object - -The `resolved` object is included in interaction payloads for user, role, mentionable, and channel select menu components. `resolved` contains a nested object with additional details about the selected options with the key of the resource type—`users`, `roles`, `channels`, and `members`. - -:::info -`members` and `users` may both be present in the `resolved` object when a user is selected (in either a user select or mentionable select). -::: - -###### Example Resolved Object - -A sample `data` object (a subset of the interaction payload) for a channel select menu component: - -```json -{ - "component_type": 8, - "custom_id": "my_channel_select", - "resolved": { - "channels": { - "986678954901234567": { - "id": "986678954901234567", - "name": "general", - "permissions": "4398046511103", - "type": 0 - } - } - }, - "values": [ - "986678954901234567" - ] -} -``` - -## Text Inputs - -Text inputs are an interactive component that render in modals. They can be used to collect short-form or long-form text. - -When defining a text input component, you can set attributes to customize the behavior and appearance of it. However, not all attributes will be returned in the [text input interaction payload](/docs/interactions/message-components#text-input-object-text-input-interaction). - -![A text input in a modal on desktop client](images/modal-desktop.png) - -###### Text Input Example - -```json -// this is a modal -{ - "title": "My Cool Modal", - "custom_id": "cool_modal", - "components": [{ - "type": 1, - "components": [{ - "type": 4, - "custom_id": "name", - "label": "Name", - "style": 1, - "min_length": 1, - "max_length": 4000, - "placeholder": "John", - "required": true - }] - }] -} -``` - -### Text Input Object - -###### Text Input Structure - -| Field | Type | Description | -|--------------|---------|---------------------------------------------------------------------------------------------------| -| type | integer | `4` for a text input | -| custom_id | string | Developer-defined identifier for the input; max 100 characters | -| style | integer | The [Text Input Style](/docs/interactions/message-components#text-input-object-text-input-styles) | -| label | string | Label for this component; max 45 characters | -| min_length? | integer | Minimum input length for a text input; min 0, max 4000 | -| max_length? | integer | Maximum input length for a text input; min 1, max 4000 | -| required? | boolean | Whether this component is required to be filled (defaults to `true`) | -| value? | string | Pre-filled value for this component; max 4000 characters | -| placeholder? | string | Custom placeholder text if the input is empty; max 100 characters | - -###### Text Input Styles - -| Name | Value | Description | -|-----------|-------|-------------------| -| Short | 1 | Single-line input | -| Paragraph | 2 | Multi-line input | - - -###### Text Input Interaction - -```json -{ - "application_id": "845027738276462632", - "channel": { - "flags": 0, - "guild_id": "772904309264089089", - "id": "772908445358620702", - "last_message_id": "113817814796417433", - "name": "general", - "nsfw": false, - "parent_id": "1113560261366927532", - "permissions": "281474976710655", - "position": 0, - "rate_limit_per_user": 0, - "topic": null, - "type": 0 - }, - "channel_id": "772908445358620702", - "data": { - "components": [ - { - "type": 1, - "components": [ - { - "custom_id": "name", - "type": 4, - "value": "John" - } - ] - } - ], - "custom_id": "cool_modal" - }, - "guild_id": "772904309264089089", - "id": "847587388497854464", - "member": { - "avatar": null, - "deaf": false, - "is_pending": false, - "joined_at": "2020-11-02T19:25:47.248000+00:00", - "mute": false, - "nick": null, - "pending": false, - "permissions": "17179869183", - "premium_since": null, - "roles": ["785609923542777878"], - "user": { - "avatar": "a_d5efa99b3eeaa7dd43acca82f5692432", - "global_name": "Mason", - "discriminator": "0", - "id": "53908232506183680", - "public_flags": 131141, - "username": "Mason" - } - }, - "token": "UNIQUE_TOKEN", - "type": 5, - "version": 1 -} -``` diff --git a/docs/interactions/overview.mdx b/docs/interactions/overview.mdx index cfecfefd1c..f2cf109bb6 100644 --- a/docs/interactions/overview.mdx +++ b/docs/interactions/overview.mdx @@ -31,17 +31,17 @@ Details about creating commands and handling command interactions are in the [Ap ### Message Components -**[Message components](/docs/interactions/message-components)** are interactive elements that can be included in the content of a message that your app sends in Discord. +**[Message components](/docs/components/reference)** are interactive elements that can be included in the content of a message that your app sends in Discord. ![Button message components in a message](images/overview-components.png) The main interactive components that apps can send in messages include: -- [Buttons](/docs/interactions/message-components#buttons) are clickable components that can be customized with different styles, texts, and emoji. -- [Static select menus](/docs/interactions/message-components#select-menus) are components that a user can open to see a list of developer-defined select options with custom labels and descriptions. -- [Auto-populated select menus](/docs/interactions/message-components#select-menu-types) are a set of four different select components that are populated with contextual Discord resources, like a list of users or channels in a server. +- [Buttons](/docs/components/reference#button) are clickable components that can be customized with different styles, texts, and emoji. +- [Static select menus](/docs/components/reference#string-select) are components that a user can open to see a list of developer-defined select options with custom labels and descriptions. +- [Auto-populated select menus](/docs/components/reference#string-select) are a set of four different select components that are populated with contextual Discord resources, like a list of users or channels in a server. -A list of all message components and details on sending and receiving component interactions is in the [Message Components](/docs/interactions/message-components) documentation. +A list of all message components and details on sending and receiving component interactions is in the [Message Components](/docs/components/reference) documentation. ### Modals @@ -49,7 +49,7 @@ A list of all message components and details on sending and receiving component ![Modals in the Discord client](images/overview-modals.png) -The only interactive component that modals can contain are [text inputs](/docs/interactions/message-components#text-inputs), which allow users to fill out single-or-multi line form inputs. +The only interactive component that modals can contain are [text inputs](/docs/components/reference#text-input), which allow users to fill out single-or-multi line form inputs. Details about creating and using modals is in the [Receiving and Responding](/docs/interactions/receiving-and-responding#interaction-response-object-modal) documentation. diff --git a/docs/interactions/receiving-and-responding.mdx b/docs/interactions/receiving-and-responding.mdx index bd4d94bcb0..8fea46156a 100644 --- a/docs/interactions/receiving-and-responding.mdx +++ b/docs/interactions/receiving-and-responding.mdx @@ -10,7 +10,7 @@ For [Slash Commands](/docs/interactions/application-commands#slash-commands), it For [User Commands](/docs/interactions/application-commands#user-commands) and [Message Commands](/docs/interactions/application-commands#message-commands), it includes the resolved user or message on which the action was taken. -For [Message Components](/docs/interactions/message-components#) it includes identifying information about the component that was used. It will also include some metadata about how the interaction was triggered: the `guild_id`, `channel`, `member` and other fields. You can find all the values in our data models below. +For [Message Components](/docs/components/reference) it includes identifying information about the component that was used. It will also include some metadata about how the interaction was triggered: the `guild_id`, `channel`, `member` and other fields. You can find all the values in our data models below. ### Interaction Object @@ -107,21 +107,21 @@ Sent in `APPLICATION_COMMAND` and `APPLICATION_COMMAND_AUTOCOMPLETE` interaction ###### Message Component Data Structure -| Field | Type | Description | -|----------------|-------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------| -| custom_id | string | [`custom_id`](/docs/interactions/message-components#custom-id) of the component | -| component_type | integer | [type](/docs/interactions/message-components#component-object-component-types) of the component | -| values?\* | array of [select option values](/docs/interactions/message-components#select-menu-object-select-option-structure) | Values the user selected in a [select menu](/docs/interactions/message-components#select-menu-object) component | -| resolved? | [resolved data](/docs/interactions/receiving-and-responding#interaction-object-resolved-data-structure) | Resolved entities from selected options | +| Field | Type | Description | +|----------------|---------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------| +| custom_id | string | [`custom_id`](/docs/components/reference#anatomy-of-a-component-custom-id) of the component | +| component_type | integer | [type](/docs/components/reference#component-object-component-types) of the component | +| values?\* | array of [select option values](/docs/components/reference#string-select-select-option-structure) | Values the user selected in a [select menu](/docs/components/reference#string-select) component | +| resolved? | [resolved data](/docs/interactions/receiving-and-responding#interaction-object-resolved-data-structure) | Resolved entities from selected options | \* This is always present for select menu components ###### Modal Submit Data Structure -| Field | Type | Description | -|------------|-----------------------------------------------------------------------------------------|-----------------------------------------------------------------------------| -| custom_id | string | [`custom_id`](/docs/interactions/message-components#custom-id) of the modal | -| components | array of [message components](/docs/interactions/message-components#message-components) | Values submitted by the user | +| Field | Type | Description | +|------------|----------------------------------------------------------------------------|-----------------------------------------------------------------------------------------| +| custom_id | string | [`custom_id`](/docs/components/reference#anatomy-of-a-component-custom-id) of the modal | +| components | array of [message components](/docs/components/reference#component-object) | Values submitted by the user | ###### Resolved Data Structure @@ -161,7 +161,7 @@ All options have names, and an option can either be a parameter and input value- This is sent on the [message object](/docs/resources/message#message-object) when the message is a response to an Interaction without an existing message. :::info -This means responses to [Message Components](/docs/interactions/message-components#) do not include this property, instead including a [message reference](/docs/resources/message#message-reference-structure) object as components _always_ exist on preexisting messages. +This means responses to [Message Components](/docs/components/reference) do not include this property, instead including a [message reference](/docs/resources/message#message-reference-structure) object as components _always_ exist on preexisting messages. ::: ###### Message Interaction Structure @@ -192,14 +192,13 @@ An [Interaction](/docs/interactions/receiving-and-responding#interaction-object) - [Slash Commands](/docs/interactions/application-commands#slash-commands-example-interaction) - [User Commands](/docs/interactions/application-commands#user-commands-example-interaction) - [Message Commands](/docs/interactions/application-commands#message-commands-example-interaction) -- [Message Components](/docs/interactions/message-components#component-interaction-object-sample-component-interaction) -- [Select Menu Message Components](/docs/interactions/message-components#select-menu-object-select-menu-interaction) +- [Message Components](/docs/components/reference#button-button-interaction) +- [Select Menu Message Components](/docs/components/reference#string-select-string-select-interaction) An explanation of all the fields can be found in our [data models](/docs/interactions/receiving-and-responding#interaction-object). Now that you've gotten the data from the user, it's time to respond to them. - ## Responding to an Interaction Interactions--both receiving and responding--are webhooks under the hood. So responding to an Interaction is just like sending a webhook request! @@ -233,7 +232,7 @@ There are a number of ways you can respond to an interaction: | PREMIUM_REQUIRED | 10 | [**Deprecated**](/docs/change-log#premium-apps-new-premium-button-style-deep-linking-url-schemes); respond to an interaction with an upgrade button, only available for apps with [monetization](/docs/monetization/overview) enabled | | LAUNCH_ACTIVITY | 12 | Launch the Activity associated with the app. Only available for apps with [Activities](/docs/activities/overview) enabled | -\* Only valid for [component-based](/docs/interactions/message-components#) interactions +\* Only valid for [component-based](/docs/components/reference) interactions \*\* Not available for `MODAL_SUBMIT` and `PING` interactions. @@ -251,7 +250,7 @@ Not all message fields are currently supported. | embeds? | array of [embeds](/docs/resources/message#embed-object) | Supports up to 10 embeds | | allowed_mentions? | [allowed mentions](/docs/resources/message#allowed-mentions-object) | [Allowed mentions](/docs/resources/message#allowed-mentions-object) object | | flags? \* | integer | [Message flags](/docs/resources/message#message-object-message-flags) combined as a [bitfield](https://en.wikipedia.org/wiki/Bit_field) (only `SUPPRESS_EMBEDS`, `EPHEMERAL`, and `SUPPRESS_NOTIFICATIONS` can be set) | -| components? | array of [components](/docs/interactions/message-components#) | Message components | +| components? | array of [components](/docs/components/reference#component-object) | Message components | | attachments? \*\* | array of partial [attachment](/docs/resources/message#attachment-object) objects | Attachment objects with filename and description | | poll? | [poll](/docs/resources/poll#poll-create-request-object) request object | Details about the poll | @@ -271,11 +270,11 @@ Not all message fields are currently supported. Support for components in modals is currently limited to type 4 (Text Input). ::: -| Field | Type | Description | -|------------|---------------------------------------------------------------|----------------------------------------------------------------| -| custom_id | string | Developer-defined identifier for the modal, max 100 characters | -| title | string | Title of the popup modal, max 45 characters | -| components | array of [components](/docs/interactions/message-components#) | Between 1 and 5 (inclusive) components that make up the modal | +| Field | Type | Description | +|------------|--------------------------------------------------------------------|----------------------------------------------------------------| +| custom_id | string | Developer-defined identifier for the modal, max 100 characters | +| title | string | Title of the popup modal, max 45 characters | +| components | array of [components](/docs/components/reference#component-object) | Between 1 and 5 (inclusive) components that make up the modal | :::warn If your application responds with user data, you should use [`allowed_mentions`](/docs/resources/message#allowed-mentions-object) to filter which mentions in the content actually ping. diff --git a/docs/monetization/implementing-app-subscriptions.mdx b/docs/monetization/implementing-app-subscriptions.mdx index 3be691aa7f..9d908702fd 100644 --- a/docs/monetization/implementing-app-subscriptions.mdx +++ b/docs/monetization/implementing-app-subscriptions.mdx @@ -87,7 +87,7 @@ When using the [Embedded App SDK](/docs/developer-tools/embedded-app-sdk) to bui [Responding with a premium button](/docs/monetization/managing-skus#responding-with-a-premium-button) gives you the ability to prompt users to subscribe to your app when they attempt to use a premium feature without a subscription. -You can do this by sending a message with a [button](/docs/interactions/message-components#buttons) with a [premium style](/docs/interactions/message-components#button-object-button-styles) and a `sku_id` that allows the user to upgrade to your premium offering. +You can do this by sending a message with a [button](/docs/components/reference#button) with a [premium style](/docs/components/reference#button-button-styles) and a `sku_id` that allows the user to upgrade to your premium offering. ### Starting a Purchase from an Activity diff --git a/docs/monetization/implementing-one-time-purchases.md b/docs/monetization/implementing-one-time-purchases.md index 8ab13209c0..6e3a6aace3 100644 --- a/docs/monetization/implementing-one-time-purchases.md +++ b/docs/monetization/implementing-one-time-purchases.md @@ -81,7 +81,7 @@ Consuming the entitlement will update the entitlement to return a true value in [Responding with a premium button](/docs/monetization/managing-skus#responding-with-a-premium-button) gives you the ability to prompt users to subscribe to your app when they attempt to use a premium feature without a subscription. -You can do this by sending a message with a [button](/docs/interactions/message-components#buttons) with a [premium style](/docs/interactions/message-components#button-object-button-styles) and a `sku_id` that allows the user to upgrade to your premium offering. +You can do this by sending a message with a [button](/docs/components/reference#button) with a [premium style](/docs/components/reference#button-button-styles) and a `sku_id` that allows the user to upgrade to your premium offering. ### Starting a Purchase from an Activity diff --git a/docs/monetization/managing-skus.mdx b/docs/monetization/managing-skus.mdx index b8450370c6..bcd6f19a19 100644 --- a/docs/monetization/managing-skus.mdx +++ b/docs/monetization/managing-skus.mdx @@ -213,7 +213,7 @@ You can link directly to your Store page using our Application Directory Store U ## Responding with a Premium Button -You can prompt users to purchase item or subscription SKUs using a [button](/docs/interactions/message-components#buttons) with a [premium style](/docs/interactions/message-components#button-object-button-styles) and a `sku_id`. You can use this premium button style anywhere you would use message components, such as in a command response. +You can prompt users to purchase item or subscription SKUs using a [button](/docs/components/reference#button) with a [premium style](/docs/components/reference#button-button-styles) and a `sku_id`. You can use this premium button style anywhere you would use message components, such as in a command response. ```javascript return new JsonResponse({ diff --git a/docs/quick-start/getting-started.mdx b/docs/quick-start/getting-started.mdx index 43e2a4d1de..960d68e909 100644 --- a/docs/quick-start/getting-started.mdx +++ b/docs/quick-start/getting-started.mdx @@ -394,7 +394,7 @@ The above code is doing a few things: The sample code uses an object as in-memory storage, but for production apps you should use a database. ::: -When sending a message with [message components](/docs/interactions/message-components#what-is-a-component), the individual payloads are appended to a `components` array. Actionable components (like buttons) need to be inside of an [action row](/docs/interactions/message-components#action-rows), which you can see in the code sample. +When sending a message with [message components](/docs/components/reference), the individual payloads are appended to a `components` array. Actionable components (like buttons) need to be inside of an [action row](/docs/components/reference#action-row), which you can see in the code sample. Note the unique `custom_id` sent with message components, in this case `accept_button_` with the active game's ID appended to it. A `custom_id` can be used to handle requests that Discord sends you when someone interacts with the component, which you'll see in a moment. @@ -458,7 +458,7 @@ The above code: 2. [Deletes the original message](/docs/interactions/receiving-and-responding#delete-original-interaction-response) calling a webhook using `node-fetch` and passing the unique interaction `token` in the request body. This is done to clean up the channel, and so other users can't click the button. 3. Responds to the request by sending a message that contains a select menu with the object choices for the game. The payload should look fairly similar to the previous one, with the exception of the `options` array and `flags: 64`, [which indicates that the message is ephemeral](/docs/interactions/receiving-and-responding#create-followup-message). -The `options` array is populated using the `getShuffledOptions()` method in `game.js`, which manipulates the `RPSChoices` values to conform to the shape of [message component options](/docs/interactions/message-components#select-menu-object-select-option-structure). +The `options` array is populated using the `getShuffledOptions()` method in `game.js`, which manipulates the `RPSChoices` values to conform to the shape of [string select options](/docs/components/reference#string-select-select-option-structure). diff --git a/docs/quick-start/overview-of-apps.mdx b/docs/quick-start/overview-of-apps.mdx index 4fda82d0e0..d771bca805 100644 --- a/docs/quick-start/overview-of-apps.mdx +++ b/docs/quick-start/overview-of-apps.mdx @@ -26,7 +26,7 @@ Messages are a core part of Discord, and that's true for apps too. Apps can send ### Interact with users -Apps can use **[interactions](/docs/interactions/overview)** to create more engaging and intuitive experiences for users. When sending messages, apps can send interactive components like [buttons](/docs/interactions/message-components#buttons) and [select menus](/docs/interactions/message-components#select-menus) in the `components` field. Apps can also open form-like modals or launch an Activity [in response to interactions](/docs/interactions/receiving-and-responding#interaction-response-object-modal). +Apps can use **[interactions](/docs/interactions/overview)** to create more engaging and intuitive experiences for users. When sending messages, apps can send interactive components like [buttons](/docs/components/reference#button) and [select menus](/docs/components/reference#string-select) in the `components` field. Apps can also open form-like modals or launch an Activity [in response to interactions](/docs/interactions/receiving-and-responding#interaction-response-object-modal). ### Build embedded games and experiences diff --git a/docs/resources/application-role-connection-metadata.mdx b/docs/resources/application-role-connection-metadata.mdx index 2d9c2d861d..5de4ed1d6f 100644 --- a/docs/resources/application-role-connection-metadata.mdx +++ b/docs/resources/application-role-connection-metadata.mdx @@ -1,6 +1,6 @@ # Application Role Connection Metadata -A representation of role connection metadata for an [application](/docs/resources/application#). +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. diff --git a/docs/resources/auto-moderation.mdx b/docs/resources/auto-moderation.mdx index 1e57a5d9fc..775c27f8d8 100644 --- a/docs/resources/auto-moderation.mdx +++ b/docs/resources/auto-moderation.mdx @@ -1,6 +1,6 @@ # Auto Moderation -Auto Moderation is a feature which allows each [guild](/docs/resources/guild#) to set up rules that trigger based on some criteria. For example, a rule can trigger whenever a message contains a specific keyword. +Auto Moderation is a feature which allows each [guild](/docs/resources/guild) to set up rules that trigger based on some criteria. For example, a rule can trigger whenever a message contains a specific keyword. Rules can be configured to automatically execute actions whenever they trigger. For example, if a user tries to send a message which contains a certain keyword, a rule can trigger and block the message before it is sent. diff --git a/docs/resources/channel.mdx b/docs/resources/channel.mdx index 26037022f4..443cbf0159 100644 --- a/docs/resources/channel.mdx +++ b/docs/resources/channel.mdx @@ -635,15 +635,15 @@ This endpoint supports the `X-Audit-Log-Reason` header. When sending a message, apps must provide a value for **at least one of** `content`, `embeds`, `sticker_ids`, `components`, or `files[n]`. ::: -| Field | Type | Description | -|-------------------|----------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| content?\* | string | Message contents (up to 2000 characters) | -| embeds?\* | array of [embed](/docs/resources/message#embed-object) objects | Up to 10 `rich` embeds (up to 6000 characters) | -| allowed_mentions? | [allowed mention object](/docs/resources/message#allowed-mentions-object) | Allowed mentions for the message | -| components?\* | array of [message component](/docs/interactions/message-components#component-object) objects | Components to include with the message | -| sticker_ids?\* | array of snowflakes | IDs of up to 3 [stickers](/docs/resources/sticker#sticker-object) in the server to send in the message | -| attachments? | array of partial [attachment](/docs/resources/message#attachment-object) objects | Attachment objects with `filename` and `description`. See [Uploading Files](/docs/reference#uploading-files) | -| flags? | integer | [Message flags](/docs/resources/message#message-object-message-flags) combined as a [bitfield](https://en.wikipedia.org/wiki/Bit_field) (only `SUPPRESS_EMBEDS` and `SUPPRESS_NOTIFICATIONS` can be set) | +| Field | Type | Description | +|-------------------|-----------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| content?\* | string | Message contents (up to 2000 characters) | +| embeds?\* | array of [embed](/docs/resources/message#embed-object) objects | Up to 10 `rich` embeds (up to 6000 characters) | +| allowed_mentions? | [allowed mention object](/docs/resources/message#allowed-mentions-object) | Allowed mentions for the message | +| components?\* | array of [message component](/docs/components/reference#component-object) objects | Components to include with the message | +| sticker_ids?\* | array of snowflakes | IDs of up to 3 [stickers](/docs/resources/sticker#sticker-object) in the server to send in the message | +| attachments? | array of partial [attachment](/docs/resources/message#attachment-object) objects | Attachment objects with `filename` and `description`. See [Uploading Files](/docs/reference#uploading-files) | +| flags? | integer | [Message flags](/docs/resources/message#message-object-message-flags) combined as a [bitfield](https://en.wikipedia.org/wiki/Bit_field) (only `SUPPRESS_EMBEDS` and `SUPPRESS_NOTIFICATIONS` can be set) | \* At least one of `content`, `embeds`, `sticker_ids`, `components`, or `files[n]` is required. diff --git a/docs/resources/guild-scheduled-event.mdx b/docs/resources/guild-scheduled-event.mdx index 2858857173..1370eaeef6 100644 --- a/docs/resources/guild-scheduled-event.mdx +++ b/docs/resources/guild-scheduled-event.mdx @@ -1,6 +1,6 @@ # Guild Scheduled Event -A representation of a scheduled event in a [guild](/docs/resources/guild#). +A representation of a scheduled event in a [guild](/docs/resources/guild). ### Guild Scheduled Event Object diff --git a/docs/resources/message.mdx b/docs/resources/message.mdx index 4b2d170543..a8d912371c 100644 --- a/docs/resources/message.mdx +++ b/docs/resources/message.mdx @@ -40,20 +40,20 @@ An app will receive empty values in the `content`, `embeds`, `attachments`, and | type | integer | [type of message](/docs/resources/message#message-object-message-types) | | activity? | [message activity](/docs/resources/message#message-object-message-activity-structure) object | sent with Rich Presence-related chat embeds | | application? | partial [application](/docs/resources/application#application-object) object | sent with Rich Presence-related chat embeds | -| application_id? | snowflake | if the message is an [Interaction](/docs/interactions/receiving-and-responding#) or application-owned webhook, this is the id of the application | +| application_id? | snowflake | if the message is an [Interaction](/docs/interactions/receiving-and-responding) or application-owned webhook, this is the id of the application | | flags? | integer | [message flags](/docs/resources/message#message-object-message-flags) combined as a [bitfield](https://en.wikipedia.org/wiki/Bit_field) | | message_reference? | [message reference](/docs/resources/message#message-reference-structure) object | data showing the source of a crosspost, channel follow add, pin, or reply message | | message_snapshots? \[5\] | array of [message snapshot](/docs/resources/message#message-snapshot-object) objects | the message associated with the `message_reference`. This is a minimal subset of fields in a message (e.g. `author` is excluded.) | | referenced_message? \[4\] | ?[message object](/docs/resources/message#message-object) | the message associated with the message_reference | -| interaction_metadata? | [message interaction metadata object](/docs/resources/message#message-interaction-metadata-object) | Sent if the message is sent as a result of an [interaction](/docs/interactions/receiving-and-responding#) | -| interaction? | [message interaction object](/docs/interactions/receiving-and-responding#message-interaction-object-message-interaction-structure) | **Deprecated in favor of `interaction_metadata`**; sent if the message is a response to an [interaction](/docs/interactions/receiving-and-responding#) | +| interaction_metadata? | [message interaction metadata object](/docs/resources/message#message-interaction-metadata-object) | Sent if the message is sent as a result of an [interaction](/docs/interactions/receiving-and-responding) | +| interaction? | [message interaction object](/docs/interactions/receiving-and-responding#message-interaction-object-message-interaction-structure) | **Deprecated in favor of `interaction_metadata`**; sent if the message is a response to an [interaction](/docs/interactions/receiving-and-responding) | | thread? | [channel](/docs/resources/channel#channel-object) object | the thread that was started from this message, includes [thread member](/docs/resources/channel#thread-member-object) object | -| components? \[2\] | array of [message components](/docs/interactions/message-components#component-object) | sent if the message contains components like buttons, action rows, or other interactive components | +| components? \[2\] | array of [message components](/docs/components/reference#component-object) | sent if the message contains components like buttons, action rows, or other interactive components | | sticker_items? | array of [message sticker item objects](/docs/resources/sticker#sticker-item-object) | sent if the message contains stickers | | stickers? | array of [sticker](/docs/resources/sticker#sticker-object) objects | **Deprecated** the stickers sent with the message | | position? | integer | A generally increasing integer (there may be gaps or duplicates) that represents the approximate position of the message in a thread, it can be used to estimate the relative position of the message in a thread in company with `total_message_sent` on parent thread | | role_subscription_data? | [role subscription data](/docs/resources/message#role-subscription-data-object) object | data of the role subscription purchase or renewal that prompted this ROLE_SUBSCRIPTION_PURCHASE message | -| resolved? | [resolved](/docs/interactions/receiving-and-responding#interaction-object-resolved-data-structure) data | data for users, members, channels, and roles in the message's [auto-populated select menus](/docs/interactions/message-components#select-menus) | +| resolved? | [resolved](/docs/interactions/receiving-and-responding#interaction-object-resolved-data-structure) data | data for users, members, channels, and roles in the message's [auto-populated select menus](/docs/components/reference#string-select-select-menu-resolved-object) | | poll? \[2\] | [poll](/docs/resources/poll#poll-object) object | A poll! | | call? | [message call](/docs/resources/message#message-call-object) object | the call associated with the message | @@ -133,20 +133,21 @@ Type `19` and `20` are only available in API v8 and above. In v6, they are repre ###### Message Flags -| Flag | Value | Description | -|----------------------------------------|-----------|-----------------------------------------------------------------------------------| -| CROSSPOSTED | `1 << 0` | this message has been published to subscribed channels (via Channel Following) | -| IS_CROSSPOST | `1 << 1` | this message originated from a message in another channel (via Channel Following) | -| SUPPRESS_EMBEDS | `1 << 2` | do not include any embeds when serializing this message | -| SOURCE_MESSAGE_DELETED | `1 << 3` | the source message for this crosspost has been deleted (via Channel Following) | -| URGENT | `1 << 4` | this message came from the urgent message system | -| HAS_THREAD | `1 << 5` | this message has an associated thread, with the same id as the message | -| EPHEMERAL | `1 << 6` | this message is only visible to the user who invoked the Interaction | -| LOADING | `1 << 7` | this message is an Interaction Response and the bot is "thinking" | -| FAILED_TO_MENTION_SOME_ROLES_IN_THREAD | `1 << 8` | this message failed to mention some roles and add their members to the thread | -| SUPPRESS_NOTIFICATIONS | `1 << 12` | this message will not trigger push and desktop notifications | -| IS_VOICE_MESSAGE | `1 << 13` | this message is a voice message | -| HAS_SNAPSHOT | `1 << 14` | this message has a snapshot (via Message Forwarding) | +| Flag | Value | Description | +|----------------------------------------|-----------|------------------------------------------------------------------------------------------------------------------| +| CROSSPOSTED | `1 << 0` | this message has been published to subscribed channels (via Channel Following) | +| IS_CROSSPOST | `1 << 1` | this message originated from a message in another channel (via Channel Following) | +| SUPPRESS_EMBEDS | `1 << 2` | do not include any embeds when serializing this message | +| SOURCE_MESSAGE_DELETED | `1 << 3` | the source message for this crosspost has been deleted (via Channel Following) | +| URGENT | `1 << 4` | this message came from the urgent message system | +| HAS_THREAD | `1 << 5` | this message has an associated thread, with the same id as the message | +| EPHEMERAL | `1 << 6` | this message is only visible to the user who invoked the Interaction | +| LOADING | `1 << 7` | this message is an Interaction Response and the bot is "thinking" | +| FAILED_TO_MENTION_SOME_ROLES_IN_THREAD | `1 << 8` | this message failed to mention some roles and add their members to the thread | +| SUPPRESS_NOTIFICATIONS | `1 << 12` | this message will not trigger push and desktop notifications | +| IS_VOICE_MESSAGE | `1 << 13` | this message is a voice message | +| HAS_SNAPSHOT | `1 << 14` | this message has a snapshot (via Message Forwarding) | +| IS_COMPONENTS_V2 | `1 << 15` | this message allows you to create fully [component](/docs/components/reference#component-object) driven messages | ###### Example Message @@ -261,7 +262,7 @@ One of [Application Command Interaction Metadata](/docs/resources/message#messag | type | [interaction type](/docs/interactions/receiving-and-responding#interaction-object-interaction-type) | Type of interaction | | user | [user](/docs/resources/user#user-object) object | User who triggered the interaction | | authorizing_integration_owners | dictionary with keys of [application integration types](/docs/resources/application#application-object-application-integration-types) | IDs for installation context(s) related to an interaction. Details in [Authorizing Integration Owners Object](/docs/interactions/receiving-and-responding#interaction-object-authorizing-integration-owners-object) | -| original_response_message_id? | snowflake | ID of the original response message, present only on [follow-up messages](/docs/interactions/receiving-and-responding#) | +| original_response_message_id? | snowflake | ID of the original response message, present only on [follow-up messages](/docs/interactions/receiving-and-responding) | | target_user? | [user](/docs/resources/user#user-object) object | The user the command was run on, present only on [user command](/docs/interactions/application-commands#user-commands) interactions | | target_message_id? | snowflake | The ID of the message the command was run on, present only on [message command](/docs/interactions/application-commands#message-commands) interactions. The original response message will also have `message_reference` and `referenced_message` pointing to this message. | @@ -274,7 +275,7 @@ One of [Application Command Interaction Metadata](/docs/resources/message#messag | type | [interaction type](/docs/interactions/receiving-and-responding#interaction-object-interaction-type) | Type of interaction | | user | [user](/docs/resources/user#user-object) object | User who triggered the interaction | | authorizing_integration_owners | dictionary with keys of [application integration types](/docs/resources/application#application-object-application-integration-types) | IDs for installation context(s) related to an interaction. Details in [Authorizing Integration Owners Object](/docs/interactions/receiving-and-responding#interaction-object-authorizing-integration-owners-object) | -| original_response_message_id? | snowflake | ID of the original response message, present only on [follow-up messages](/docs/interactions/receiving-and-responding#) | +| original_response_message_id? | snowflake | ID of the original response message, present only on [follow-up messages](/docs/interactions/receiving-and-responding) | | interacted_message_id | snowflake | ID of the message that contained the interactive component | @@ -286,7 +287,7 @@ One of [Application Command Interaction Metadata](/docs/resources/message#messag | type | [interaction type](/docs/interactions/receiving-and-responding#interaction-object-interaction-type) | Type of interaction | | user | [user](/docs/resources/user#user-object) object | User who triggered the interaction | | authorizing_integration_owners | dictionary with keys of [application integration types](/docs/resources/application#application-object-application-integration-types) | IDs for installation context(s) related to an interaction. Details in [Authorizing Integration Owners Object](/docs/interactions/receiving-and-responding#interaction-object-authorizing-integration-owners-object) | -| original_response_message_id? | snowflake | ID of the original response message, present only on [follow-up messages](/docs/interactions/receiving-and-responding#) | +| original_response_message_id? | snowflake | ID of the original response message, present only on [follow-up messages](/docs/interactions/receiving-and-responding) | | triggering_interaction_metadata | [Application Command Interaction Metadata](/docs/resources/message#message-interaction-metadata-object-application-command-interaction-metadata-structure) or [Message Component Interaction Metadata](/docs/resources/message#message-interaction-metadata-object-message-component-interaction-metadata-structure) object | Metadata for the interaction that was used to open the modal | @@ -792,22 +793,22 @@ Files must be attached using a `multipart/form-data` body as described in [Uploa When creating a message, apps must provide a value for **at least one of** `content`, `embeds`, `sticker_ids`, `components`, `files[n]`, or `poll`. ::: -| Field | Type | Description | -|--------------------|----------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| content?\* | string | Message contents (up to 2000 characters) | -| nonce? | integer or string | Can be used to verify a message was sent (up to 25 characters). Value will appear in the [Message Create event](/docs/events/gateway-events#message-create). | -| tts? | boolean | `true` if this is a TTS message | -| embeds?\* | array of [embed](/docs/resources/message#embed-object) objects | Up to 10 `rich` embeds (up to 6000 characters) | -| allowed_mentions? | [allowed mention object](/docs/resources/message#allowed-mentions-object) | Allowed mentions for the message | -| message_reference? | [message reference](/docs/resources/message#message-reference-structure) | Include to make your message a reply or a forward | -| components?\* | array of [message component](/docs/interactions/message-components#component-object) objects | Components to include with the message | -| sticker_ids?\* | array of snowflakes | IDs of up to 3 [stickers](/docs/resources/sticker#sticker-object) in the server to send in the message | -| files[n]?\* | file contents | Contents of the file being sent. See [Uploading Files](/docs/reference#uploading-files) | -| payload_json? | string | JSON-encoded body of non-file params, only for `multipart/form-data` requests. See [Uploading Files](/docs/reference#uploading-files) | -| attachments? | array of partial [attachment](/docs/resources/message#attachment-object) objects | Attachment objects with filename and description. See [Uploading Files](/docs/reference#uploading-files) | -| flags? | integer | [Message flags](/docs/resources/message#message-object-message-flags) combined as a [bitfield](https://en.wikipedia.org/wiki/Bit_field) (only `SUPPRESS_EMBEDS` and `SUPPRESS_NOTIFICATIONS` can be set) | -| enforce_nonce? | boolean | If true and nonce is present, it will be checked for uniqueness in the past few minutes. If another message was created by the same author with the same nonce, that message will be returned and no new message will be created. | -| poll? | [poll](/docs/resources/poll#poll-create-request-object) request object | A poll! | +| Field | Type | Description | +|--------------------|-----------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| content?\* | string | Message contents (up to 2000 characters) | +| nonce? | integer or string | Can be used to verify a message was sent (up to 25 characters). Value will appear in the [Message Create event](/docs/events/gateway-events#message-create). | +| tts? | boolean | `true` if this is a TTS message | +| embeds?\* | array of [embed](/docs/resources/message#embed-object) objects | Up to 10 `rich` embeds (up to 6000 characters) | +| allowed_mentions? | [allowed mention object](/docs/resources/message#allowed-mentions-object) | Allowed mentions for the message | +| message_reference? | [message reference](/docs/resources/message#message-reference-structure) | Include to make your message a reply or a forward | +| components?\* | array of [message component](/docs/components/reference#component-object) objects | Components to include with the message | +| sticker_ids?\* | array of snowflakes | IDs of up to 3 [stickers](/docs/resources/sticker#sticker-object) in the server to send in the message | +| files[n]?\* | file contents | Contents of the file being sent. See [Uploading Files](/docs/reference#uploading-files) | +| payload_json? | string | JSON-encoded body of non-file params, only for `multipart/form-data` requests. See [Uploading Files](/docs/reference#uploading-files) | +| attachments? | array of partial [attachment](/docs/resources/message#attachment-object) objects | Attachment objects with filename and description. See [Uploading Files](/docs/reference#uploading-files) | +| flags? | integer | [Message flags](/docs/resources/message#message-object-message-flags) combined as a [bitfield](https://en.wikipedia.org/wiki/Bit_field) (only `SUPPRESS_EMBEDS` and `SUPPRESS_NOTIFICATIONS` can be set) | +| enforce_nonce? | boolean | If true and nonce is present, it will be checked for uniqueness in the past few minutes. If another message was created by the same author with the same nonce, that message will be returned and no new message will be created. | +| poll? | [poll](/docs/resources/poll#poll-create-request-object) request object | A poll! | \* At least one of `content`, `embeds`, `sticker_ids`, `components`, `files[n]`, or `poll` is required. @@ -905,16 +906,16 @@ All parameters to this endpoint are optional and nullable. ###### JSON/Form Params -| Field | Type | Description | -|------------------|--------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------| -| content | string | Message contents (up to 2000 characters) | -| embeds | array of [embed](/docs/resources/message#embed-object) objects | Up to 10 `rich` embeds (up to 6000 characters) | -| flags | integer | Edit the [flags](/docs/resources/message#message-object-message-flags) of a message (only `SUPPRESS_EMBEDS` can currently be set/unset) | -| allowed_mentions | [allowed mention object](/docs/resources/message#allowed-mentions-object) | Allowed mentions for the message | -| components | array of [message component](/docs/interactions/message-components#component-object) | Components to include with the message | -| files[n] | file contents | Contents of the file being sent/edited. See [Uploading Files](/docs/reference#uploading-files) | -| payload_json | string | JSON-encoded body of non-file params (multipart/form-data only). See [Uploading Files](/docs/reference#uploading-files) | -| attachments | array of [attachment](/docs/resources/message#attachment-object) objects | Attached files to keep and possible descriptions for new files. See [Uploading Files](/docs/reference#uploading-files) | +| Field | Type | Description | +|------------------|---------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------| +| content | string | Message contents (up to 2000 characters) | +| embeds | array of [embed](/docs/resources/message#embed-object) objects | Up to 10 `rich` embeds (up to 6000 characters) | +| flags | integer | Edit the [flags](/docs/resources/message#message-object-message-flags) of a message (only `SUPPRESS_EMBEDS` can currently be set/unset) | +| allowed_mentions | [allowed mention object](/docs/resources/message#allowed-mentions-object) | Allowed mentions for the message | +| components | array of [message component](/docs/components/reference#component-object) | Components to include with the message | +| files[n] | file contents | Contents of the file being sent/edited. See [Uploading Files](/docs/reference#uploading-files) | +| payload_json | string | JSON-encoded body of non-file params (multipart/form-data only). See [Uploading Files](/docs/reference#uploading-files) | +| attachments | array of [attachment](/docs/resources/message#attachment-object) objects | Attached files to keep and possible descriptions for new files. See [Uploading Files](/docs/reference#uploading-files) | ## Delete Message /channels/[\{channel.id\}](/docs/resources/channel#channel-object)/messages/[\{message.id\}](/docs/resources/message#message-object) diff --git a/docs/resources/user.mdx b/docs/resources/user.mdx index 2c42ceceea..ea7a93b807 100644 --- a/docs/resources/user.mdx +++ b/docs/resources/user.mdx @@ -82,7 +82,7 @@ There are other rules and restrictions not shared here for the sake of spam and | `1 << 7` | HYPESQUAD_ONLINE_HOUSE_2 | House Brilliance Member | | `1 << 8` | HYPESQUAD_ONLINE_HOUSE_3 | House Balance Member | | `1 << 9` | PREMIUM_EARLY_SUPPORTER | Early Nitro Supporter | -| `1 << 10` | TEAM_PSEUDO_USER | User is a [team](/docs/topics/teams#) | +| `1 << 10` | TEAM_PSEUDO_USER | User is a [team](/docs/topics/teams) | | `1 << 14` | BUG_HUNTER_LEVEL_2 | Bug Hunter Level 2 | | `1 << 16` | VERIFIED_BOT | Verified Bot | | `1 << 17` | VERIFIED_DEVELOPER | Early Verified Bot Developer | diff --git a/docs/resources/webhook.mdx b/docs/resources/webhook.mdx index f17d12a5ea..98c51c435b 100644 --- a/docs/resources/webhook.mdx +++ b/docs/resources/webhook.mdx @@ -212,32 +212,32 @@ Discord may strip certain characters from message content, like invalid unicode ###### Query String Params -| Field | Type | Description | Required | -|-----------------|--------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------| -| wait | [boolean](/docs/reference#boolean-query-strings) | waits for server confirmation of message send before response, and returns the created message body (defaults to `false`; when `false` a message that is not saved does not return an error) | false | -| thread_id | snowflake | Send a message to the specified thread within a webhook's channel. The thread will automatically be unarchived. | false | -| with_components | [boolean](/docs/reference#boolean-query-strings) | whether to allow sending (non-interactive) components for non-application-owned webhooks (defaults to `false`; ignored for application-owned webhooks) | false | +| Field | Type | Description | Required | +|-----------------|--------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------| +| wait | [boolean](/docs/reference#boolean-query-strings) | waits for server confirmation of message send before response, and returns the created message body (defaults to `false`; when `false` a message that is not saved does not return an error) | false | +| thread_id | snowflake | Send a message to the specified thread within a webhook's channel. The thread will automatically be unarchived. | false | +| with_components | [boolean](/docs/reference#boolean-query-strings) | whether to respect the `components` field of the request. When enabled, allows application-owned webhooks to use all components and non-owned webhooks to use non-interactive components. (defaults to `false`) | false | ###### JSON/Form Params -| Field | Type | Description | Required | -|-------------------|--------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------| -| content | string | the message contents (up to 2000 characters) | one of content, file, embeds, poll | -| username | string | override the default username of the webhook | false | -| avatar_url | string | override the default avatar of the webhook | false | -| tts | boolean | true if this is a TTS message | false | -| embeds | array of up to 10 [embed](/docs/resources/message#embed-object) objects | embedded `rich` content | one of content, file, embeds, poll | -| allowed_mentions | [allowed mention object](/docs/resources/message#allowed-mentions-object) | allowed mentions for the message | false | -| components \* | array of [message component](/docs/interactions/message-components#component-object) | the components to include with the message | false | -| files[n] \*\* | file contents | the contents of the file being sent | one of content, file, embeds, poll | -| payload_json \*\* | string | JSON encoded body of non-file params | `multipart/form-data` only | -| attachments \*\* | array of partial [attachment](/docs/resources/message#attachment-object) objects | attachment objects with filename and description | false | -| flags | integer | [message flags](/docs/resources/message#message-object-message-flags) combined as a [bitfield](https://en.wikipedia.org/wiki/Bit_field) (only `SUPPRESS_EMBEDS` and `SUPPRESS_NOTIFICATIONS` can be set) | false | -| thread_name | string | name of thread to create (requires the webhook channel to be a forum or media channel) | false | -| applied_tags | array of snowflakes | array of tag ids to apply to the thread (requires the webhook channel to be a forum or media channel) | false | -| poll | [poll](/docs/resources/poll#poll-create-request-object) request object | A poll! | one of content, file, embeds, poll | - -\* Application-owned webhooks can always send components. Non-application-owned webhooks cannot send interactive components, and the field will be ignored unless they set the `with_components` query param. +| Field | Type | Description | Required | +|-------------------|----------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------| +| content | string | the message contents (up to 2000 characters) | one of content, file, embeds, poll | +| username | string | override the default username of the webhook | false | +| avatar_url | string | override the default avatar of the webhook | false | +| tts | boolean | true if this is a TTS message | false | +| embeds | array of up to 10 [embed](/docs/resources/message#embed-object) objects | embedded `rich` content | one of content, file, embeds, poll | +| allowed_mentions | [allowed mention object](/docs/resources/message#allowed-mentions-object) | allowed mentions for the message | false | +| components \* | array of [message component](/docs/components/reference#component-object) | the components to include with the message | false | +| files[n] \*\* | file contents | the contents of the file being sent | one of content, file, embeds, poll | +| payload_json \*\* | string | JSON encoded body of non-file params | `multipart/form-data` only | +| attachments \*\* | array of partial [attachment](/docs/resources/message#attachment-object) objects | attachment objects with filename and description | false | +| flags | integer | [message flags](/docs/resources/message#message-object-message-flags) combined as a [bitfield](https://en.wikipedia.org/wiki/Bit_field) (only `SUPPRESS_EMBEDS` and `SUPPRESS_NOTIFICATIONS` can be set) | false | +| thread_name | string | name of thread to create (requires the webhook channel to be a forum or media channel) | false | +| applied_tags | array of snowflakes | array of tag ids to apply to the thread (requires the webhook channel to be a forum or media channel) | false | +| poll | [poll](/docs/resources/poll#poll-create-request-object) request object | A poll! | one of content, file, embeds, poll | + +\* Application-owned webhooks can always send components. Non-application-owned webhooks cannot send interactive components, and the `components` field will be ignored unless they set the `with_components` query param. \*\* See [Uploading Files](/docs/reference#uploading-files) for details. @@ -300,25 +300,25 @@ All parameters to this endpoint are optional and nullable. ###### Query String Params -| Field | Type | Description | Required | -|-----------------|--------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|----------| -| thread_id | snowflake | id of the thread the message is in | false | -| with_components | [boolean](/docs/reference#boolean-query-strings) | whether to allow sending (non-interactive) components for non-application-owned webhooks (defaults to `false`; ignored for application-owned webhooks) | false | +| Field | Type | Description | Required | +|-----------------|--------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------| +| thread_id | snowflake | id of the thread the message is in | false | +| with_components | [boolean](/docs/reference#boolean-query-strings) | whether to respect the `components` field of the request. When enabled, allows application-owned webhooks to use all components and non-owned webhooks to use non-interactive components. (defaults to `false`) | false | ###### JSON/Form Params -| Field | Type | Description | -|-------------------|--------------------------------------------------------------------------------------|-----------------------------------------------------------------| -| content | string | the message contents (up to 2000 characters) | -| embeds | array of up to 10 [embed](/docs/resources/message#embed-object) objects | embedded `rich` content | -| allowed_mentions | [allowed mention object](/docs/resources/message#allowed-mentions-object) | allowed mentions for the message | -| components \* | array of [message component](/docs/interactions/message-components#component-object) | the components to include with the message | -| files[n] \*\* | file contents | the contents of the file being sent/edited | -| payload_json \*\* | string | JSON encoded body of non-file params (multipart/form-data only) | -| attachments \*\* | array of partial [attachment](/docs/resources/message#attachment-object) objects | attached files to keep and possible descriptions for new files | -| poll \*\*\* | [poll](/docs/resources/poll#poll-create-request-object) request object | A poll! | - -\* Application-owned webhooks can always send components. Non-application-owned webhooks cannot send interactive components, and the field will be ignored unless they set the `with_components` query param. +| Field | Type | Description | +|-------------------|----------------------------------------------------------------------------------|-----------------------------------------------------------------| +| content | string | the message contents (up to 2000 characters) | +| embeds | array of up to 10 [embed](/docs/resources/message#embed-object) objects | embedded `rich` content | +| allowed_mentions | [allowed mention object](/docs/resources/message#allowed-mentions-object) | allowed mentions for the message | +| components \* | array of [message component](/docs/components/reference#component-object) | the components to include with the message | +| files[n] \*\* | file contents | the contents of the file being sent/edited | +| payload_json \*\* | string | JSON encoded body of non-file params (multipart/form-data only) | +| attachments \*\* | array of partial [attachment](/docs/resources/message#attachment-object) objects | attached files to keep and possible descriptions for new files | +| poll \*\*\* | [poll](/docs/resources/poll#poll-create-request-object) request object | A poll! | + +\* Application-owned webhooks can always send components. Non-application-owned webhooks cannot send interactive components, and the `components` field will be ignored unless they set the `with_components` query param. \*\* See [Uploading Files](/docs/reference#uploading-files) for details. diff --git a/docs/rich-presence/using-with-the-game-sdk.mdx b/docs/rich-presence/using-with-the-game-sdk.mdx index d83b1b1256..4940835a2a 100644 --- a/docs/rich-presence/using-with-the-game-sdk.mdx +++ b/docs/rich-presence/using-with-the-game-sdk.mdx @@ -233,4 +233,4 @@ Yes! In addition to uploading an asset and specifying its name, you can also spe #### Q: OK—I've got it working! Now, how do I make my integration look _awesome_? -I'm happy ~~we preempted your question~~ you asked! Check out our [Rich Presence Best Practices](/docs/rich-presence/best-practices#) guide for a rundown on how to make your integration the best that it can be! +I'm happy ~~we preempted your question~~ you asked! Check out our [Rich Presence Best Practices](/docs/rich-presence/best-practices) guide for a rundown on how to make your integration the best that it can be! diff --git a/docs/topics/oauth2.mdx b/docs/topics/oauth2.mdx index e361606e54..99657bf945 100644 --- a/docs/topics/oauth2.mdx +++ b/docs/topics/oauth2.mdx @@ -288,7 +288,7 @@ Bot authorization is a special server-less and callback-less OAuth2 flow that ma |----------------------|-----------------------------------------------------------------------| | client_id | your app's client id | | scope | needs to include `bot` for the bot flow | -| permissions | the [permissions](/docs/topics/permissions#) you're requesting | +| permissions | the [permissions](/docs/topics/permissions) you're requesting | | guild_id | pre-fills the dropdown picker with a guild for the user | | disable_guild_select | `true` or `false`—disallows the user from changing the guild dropdown | diff --git a/docs/topics/opcodes-and-status-codes.md b/docs/topics/opcodes-and-status-codes.md index ef641b3966..74ce2e707e 100644 --- a/docs/topics/opcodes-and-status-codes.md +++ b/docs/topics/opcodes-and-status-codes.md @@ -357,7 +357,7 @@ Along with the HTTP error code, our API can also return more detailed error code ## RPC -RPC is the [local Discord server](/docs/topics/rpc#) running on localhost. Access to the RPC server requires approval from Discord. +RPC is the [local Discord server](/docs/topics/rpc) running on localhost. Access to the RPC server requires approval from Discord. ###### RPC Error Codes diff --git a/docs/tutorials/hosting-on-cloudflare-workers.md b/docs/tutorials/hosting-on-cloudflare-workers.md index 95e6196c02..caef2596b1 100644 --- a/docs/tutorials/hosting-on-cloudflare-workers.md +++ b/docs/tutorials/hosting-on-cloudflare-workers.md @@ -4,7 +4,7 @@ sidebar_label: Hosting on Cloudflare Workers # Hosting a Reddit API Discord app on Cloudflare Workers -When building Discord apps, your app can receive common events from the client as [webhooks](/docs/resources/webhook) when users interact with your app through interactions like [application commands](/docs/interactions/application-commands) or [message components](/docs/interactions/message-components). +When building Discord apps, your app can receive common events from the client as [webhooks](/docs/resources/webhook) when users interact with your app through interactions like [application commands](/docs/interactions/application-commands) or [message components](/docs/components/reference). Discord will send these events to a pre-configured HTTPS endpoint (called an Interactions Endpoint URL in an app's configuration) as a JSON payload with details about the event. @@ -350,6 +350,6 @@ In case you need to reference any of the code, you can find the repo [on GitHub] With your app built and deployed, you can start customizing it to be your own: -- Use **[message components](/docs/interactions/message-components)** in your app to add more interactivity (like buttons and select menus). +- Use **[message components](/docs/components/reference)** in your app to add more interactivity (like buttons and select menus). - Take a look at different **[public APIs](https://github.com/public-apis/public-apis)** on GitHub. - Join the **[Discord Developers server](https://discord.gg/discord-developers)** to ask questions about the API, attend events hosted by the Discord API team, and interact with other developers. diff --git a/static/images/components/action-row.png b/static/images/components/action-row.png new file mode 100644 index 0000000000..376bf28294 Binary files /dev/null and b/static/images/components/action-row.png differ diff --git a/static/images/components/channel-select.png b/static/images/components/channel-select.png new file mode 100644 index 0000000000..ab89bda496 Binary files /dev/null and b/static/images/components/channel-select.png differ diff --git a/static/images/components/container.png b/static/images/components/container.png new file mode 100644 index 0000000000..68c71c2e58 Binary files /dev/null and b/static/images/components/container.png differ diff --git a/static/images/components/file.png b/static/images/components/file.png new file mode 100644 index 0000000000..28076faa40 Binary files /dev/null and b/static/images/components/file.png differ diff --git a/static/images/components/hero.png b/static/images/components/hero.png new file mode 100644 index 0000000000..5245070138 Binary files /dev/null and b/static/images/components/hero.png differ diff --git a/static/images/components/media-gallery.png b/static/images/components/media-gallery.png new file mode 100644 index 0000000000..6b567864e3 Binary files /dev/null and b/static/images/components/media-gallery.png differ diff --git a/static/images/components/mentionable-select.png b/static/images/components/mentionable-select.png new file mode 100644 index 0000000000..07c29c7baf Binary files /dev/null and b/static/images/components/mentionable-select.png differ diff --git a/static/images/components/modal.png b/static/images/components/modal.png new file mode 100644 index 0000000000..765426ee09 Binary files /dev/null and b/static/images/components/modal.png differ diff --git a/static/images/components/role-select.png b/static/images/components/role-select.png new file mode 100644 index 0000000000..953881aca1 Binary files /dev/null and b/static/images/components/role-select.png differ diff --git a/static/images/components/section.png b/static/images/components/section.png new file mode 100644 index 0000000000..af9d7dd987 Binary files /dev/null and b/static/images/components/section.png differ diff --git a/static/images/components/separator.png b/static/images/components/separator.png new file mode 100644 index 0000000000..f7282988a9 Binary files /dev/null and b/static/images/components/separator.png differ diff --git a/static/images/components/string-select.png b/static/images/components/string-select.png new file mode 100644 index 0000000000..b8a02c2923 Binary files /dev/null and b/static/images/components/string-select.png differ diff --git a/static/images/components/text-display.png b/static/images/components/text-display.png new file mode 100644 index 0000000000..f42211b847 Binary files /dev/null and b/static/images/components/text-display.png differ diff --git a/static/images/components/user-select.png b/static/images/components/user-select.png new file mode 100644 index 0000000000..ce64e5c39c Binary files /dev/null and b/static/images/components/user-select.png differ