diff --git a/docs/Change_Log.md b/docs/Change_Log.md index 7a9d861845..ffe52a3c41 100644 --- a/docs/Change_Log.md +++ b/docs/Change_Log.md @@ -1,5 +1,19 @@ # Change Log +## Changes to Slash Command Response Types and Flags + +## March 5, 2021 + +Changes to interaction response types have been made to support better designs for Slash Commands: + +- Type `2` `Acknowledge` has been deprecated +- Type `3` `ChannelMessage` has been deprecated +- Type `5` `AcknowledgeWithSource` has been renamed to `DeferredChannelMessageWithSource` + +These deprecated types will be removed and break on **April 9, 2021**. + +Additionally, `flags` has been documented on [InteractionApplicationCommandCallbackData](#DOCS_INTERACTIONS_SLASH_COMMANDS/InteractionApplicationCommandCallbackData). Setting `flags` to `64` will make the interaction response ephemeral. + ## Slash Commands in DMs #### February 9, 2021 diff --git a/docs/interactions/Slash_Commands.md b/docs/interactions/Slash_Commands.md index ddf3790b81..1187292e99 100644 --- a/docs/interactions/Slash_Commands.md +++ b/docs/interactions/Slash_Commands.md @@ -842,24 +842,29 @@ All options have names, and an option can either be a parameter and input value- ## Interaction Response -After receiving an interaction, you must respond to acknowledge it. This may be a `pong` for a `ping`, a message, or simply an acknowledgement that you have received it and will handle the command async. +After receiving an interaction, you must respond to acknowledge it. You can choose to respond with a message immediately using type `4`, or you can choose to send a deferred response with type `5`. If choosing a deferred response, the user will see a loading state for the interaction, and you'll have up to 15 minutes to edit the original deferred response using [Edit Original Interaction Response](#DOCS_INTERACTIONS_SLASH_COMMANDS/edit-original-interaction-response). -Interaction responses may choose to "eat" the user's command input if you do not wish to have their slash command show up as message in chat. This may be helpful for slash commands, or commands whose responses are asynchronous or ephemeral messages. +![A deferred response tells the user "Bot name is thinking"](ephemeral-example.png) + +Interaction responses can also be public—everyone can see it—or "ephemeral"—only the invoking user can see it. That is determined by setting `flags` to `64` on the [InteractionApplicationCommandCallbackData](#DOCS_INTERACTIONS_SLASH_COMMANDS/InteractionApplicationCommandCallbackData). | Field | Type | Description | |-------|-------------------------------------------|------------------------------| | type | InteractionResponseType | the type of response | | data? | InteractionApplicationCommandCallbackData | an optional response message | +> warn +> Interaction response types `2` and `3` have been deprecated + ###### InteractionResponseType | Name | Value | Description | |--------------------------|-------|-------------------------------------------------------------------| | Pong | 1 | ACK a `Ping` | -| Acknowledge | 2 | ACK a command without sending a message, eating the user's input | -| ChannelMessage | 3 | respond with a message, eating the user's input | -| ChannelMessageWithSource | 4 | respond with a message, showing the user's input | -| AcknowledgeWithSource | 5 | ACK a command without sending a message, showing the user's input | +| Acknowledge | 2 | **DEPRECATED** ACK a command without sending a message, eating the user's input | +| ChannelMessage | 3 | **DEPRECATED** respond with a message, eating the user's input | +| ChannelMessageWithSource | 4 | respond to an interaction with a message | +| DeferredChannelMessageWithSource | 5 | ACK an interaction and edit to a response later, the user sees a loading state | ###### InteractionApplicationCommandCallbackData @@ -868,6 +873,18 @@ Not all message fields are currently supported. | Name | Value | Description | |-------------------|----------------------------------------------------------|---------------------------------------------------------------------------------------------| | tts? | boolean | is the response TTS | -| content | string | message content | +| content? | string | message content | | embeds? | array of [embeds](#DOCS_RESOURCES_CHANNEL/embed-object) | supports up to 10 embeds | | allowed_mentions? | allowed mentions | [allowed mentions](#DOCS_RESOURCES_CHANNEL/allowed-mentions-object) object | +| flags? | int | set to `64` to make your response ephemeral | + +## MessageInteraction + +This is sent on the [message object](#DOCS_RESOURCES_CHANNEL/message-object) when the message is a response to an Interaction. + +| Name | Value | Description | +| --- | --- | --- | +| id | snowflake | id of the interaction | +| type | InteractionType | the type of interaction | +| name | string | the name of the [ApplicationCommand](#DOCS_INTERACTIONS_SLASH_COMMANDS/applicationcommand) | +| user | [user object](#DOCS_RESOURCES_USER/user-object) | the user who invoked the interaction | diff --git a/docs/resources/Channel.md b/docs/resources/Channel.md index 84c6279625..8239072ada 100644 --- a/docs/resources/Channel.md +++ b/docs/resources/Channel.md @@ -204,6 +204,7 @@ Represents a message sent in a channel within Discord. | flags? | integer | [message flags](#DOCS_RESOURCES_CHANNEL/message-object-message-flags) combined as a [bitfield](https://en.wikipedia.org/wiki/Bit_field) | | stickers? | array of [sticker](#DOCS_RESOURCES_CHANNEL/message-object-message-sticker-structure) objects | the stickers sent with the message (bots currently can only receive messages with stickers, not send) | | referenced_message?\*\*\*\*\* | ?[message object](#DOCS_RESOURCES_CHANNEL/message-object) | the message associated with the message_reference | +| interaction? | [message interaction object](#DOCS_INTERACTIONS_SLASH_COMMANDS/messageinteraction) | sent if the message is a response to an [Interaction](#DOCS_INTERACTIONS_SLASH_COMMANDS/) | \* The author object follows the structure of the user object, but is only a valid user in the case where the message is generated by a user or bot user. If the message is generated by a webhook, the author object corresponds to the webhook's id, username, and avatar. You can tell if a message is generated by a webhook by checking for the `webhook_id` on the message object. diff --git a/images/deferred-example.png b/images/deferred-example.png new file mode 100644 index 0000000000..99daf305b4 Binary files /dev/null and b/images/deferred-example.png differ