Learn how to receive and respond to user interactions.
An Interaction is the message that your application receives when a user uses an application command or a message component.For Slash Commands, it includes the values that the user submitted.For User Commands and Message Commands, it includes the resolved user or message on which the action was taken.For 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.
Mapping of installation contexts that the interaction was authorized for to related user or guild IDs. See Authorizing Integration Owners Object for details
* This is always present on application command, message component, and modal submit interaction types. It is optional for future-proofing against new interaction types** member is sent when the interaction is invoked in a guild, and user is sent when invoked in a DM*** app_permissions includes ATTACH_FILES | EMBED_LINKS | MENTION_EVERYONE permissions for (G)DMs with other users, and additionally includes USE_EXTERNAL_EMOJIS for DMs with the app’s bot user**** This is available on all interaction types except PING
Interaction Type
Name
Value
PING
1
APPLICATION_COMMAND
2
MESSAGE_COMPONENT
3
APPLICATION_COMMAND_AUTOCOMPLETE
4
MODAL_SUBMIT
5
Interaction Context Types
Context in Discord where an interaction can be used, or where it was triggered from. Details about using interaction contexts for application commands is in the commands context documentation.
Name
Type
Description
GUILD
0
Interaction can be used within servers
BOT_DM
1
Interaction can be used within DMs with the app’s bot user
PRIVATE_CHANNEL
2
Interaction can be used within Group DMs and DMs other than the app’s bot user
Authorizing Integration Owners Object
The authorizing_integration_owners field includes details about the authorizing user or server for the installation(s) relevant to the interaction. For apps installed to a user, it can be used to tell the difference between the authorizing user and the user that triggered an interaction (like a message component).A key will only be present if the following are true:
The app has been authorized to the installation context corresponding to the key (GUILD_INSTALL or USER_INSTALL)
The interaction is supported in the source interaction context (GUILD, BOT_DM, or PRIVATE_CHANNEL) for the installation context corresponding to the key
And for command invocations, the command must be supported in the installation context (using integration_types)
The values in authorizing_integration_owners depend on the key—
If the key is GUILD_INSTALL ("0"), the value depends on the source of the interaction:
The value will be the guild ID if the interaction is triggered from a server
The value will be "0" if the interaction is triggered from a DM with the app’s bot user
If the key is USER_INSTALL ("1"), the value will be the ID of the authorizing user
Interaction Data
While the data field is guaranteed to be present for all interaction types besides PING, its structure will vary. The following tables detail the inner data payload for each interaction type.
* Partial Member objects are missing user, deaf and mute fields** Partial Channel objects only have id, name, type, permissions, last_message_id, last_pin_timestamp, nsfw, parent_id, guild_id, flags, rate_limit_per_user, topic and position fields. Threads will also have the thread_metadata field.
Application Command Interaction Data Option Structure
All options have names, and an option can either be a parameter and input value—in which case value will be set—or it can denote a subcommand or group—in which case it will contain a top-level key and another array of options.value and options are mutually exclusive.
This is sent on the message object when the message is a response to an Interaction without an existing message.
This means responses to Message Components do not include this property, instead including a message reference object as components always exist on preexisting messages.
These two methods are mutually exclusive; you can only receive Interactions one of the two ways. The INTERACTION_CREATEGateway Event may be handled by connected clients, while the webhook method detailed below does not require a connected client.If you want to receive interactions via HTTP-based outgoing webhooks, you must configure an Interactions Endpoint URL for your app. You can read about preparing and adding an Interactions Endpoint URL to your app in the Preparing for Interactions section in Interactions Overview.
An Interaction includes metadata to aid your application in handling it as well as data specific to the interaction type. You can find samples for each interaction type on their respective pages:
* If you create a callback with the typeDEFERRED_CHANNEL_MESSAGE_WITH_SOURCE the only valid message flag you may use is EPHEMERAL. If you’d like to create a component based message with IS_COMPONENTS_V2 you must do that with the edit original response endpoint, not this one.** See Uploading Files for details.
When responding to an interaction received, you can make a POST request to /interactions/<interaction_id>/<interaction_token>/callback. interaction_id is the unique id of that individual Interaction from the received payload. interaction_token is the unique token for that interaction from the received payload.If you are receiving Interactions over the gateway, you have to respond via HTTP. Responses to Interactions are not sent as commands over the gateway.If you send this request for an interaction received over HTTP, respond to the original HTTP request with a 202 and no body.
Copy
Ask AI
import requestsurl = "https://discord.com/api/v10/interactions/<interaction_id>/<interaction_token>/callback"json = { "type": 4, "data": { "content": "Congrats on sending your command!" }}r = requests.post(url, json=json)
Interaction tokens are valid for 15 minutes and can be used to send followup messages but you must send an initial response within 3 seconds of receiving the event. If the 3 second deadline is exceeded, the token will be invalidated.
Inline HTTP Response Behavior
If you receive interactions over HTTP, your server can also respond to the received POST request. You’ll want to respond with a 200 status code (if everything went well), as well as specifying a type and data, which is an Interaction Response object:
Sometimes, you want to send followup messages to a user after responding to an interaction. Or, you may want to edit your original response. Whether you receive Interactions over the gateway or by outgoing webhook, you can use the following endpoints to edit your initial response or send followup messages:
Create a response to an Interaction. Body is an interaction response. Returns 204 unless with_response is set to true which returns 200 with the body as interaction callback response.This endpoint also supports file attachments similar to the webhook endpoints. Refer to Uploading Files for details on uploading files and multipart/form-data requests.
Apps are limited to 5 followup messages per interaction if it was initiated from a user-installed app and isn’t installed in the server (meaning the authorizing integration owners object only contains USER_INSTALL)
Create a followup message for an Interaction. Functions the same as Execute Webhook, but wait is always true. The thread_id, avatar_url, and username parameters are not supported when using this endpoint for interaction followups. You can use the EPHEMERALmessage flag1 << 6 (64) to send a message that only the user can see. You can also use the IS_COMPONENTS_V2message flag1 << 15 (32768) to send a component-based message.When using this endpoint directly after responding to an interaction with DEFERRED_CHANNEL_MESSAGE_WITH_SOURCE, this endpoint will function as Edit Original Interaction Response for backwards compatibility. In this case, no new message will be created, and the loading message will be edited instead. The ephemeral flag will be ignored, and the value you provided in the initial defer response will be preserved, as an existing message’s ephemeral state cannot be changed. This behavior is deprecated, and you should use the Edit Original Interaction Response endpoint in this case instead.
