Receiving and Responding to 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.

* 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

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.

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

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.

* This can be partial when in response to APPLICATION_COMMAND_AUTOCOMPLETE

* This is always present for select menu components

Response structures for both modal and message component interactions.

* Partial Member objects are missing user, deaf and mute fields

** Partial Channel objects only have id, name, type, permissions, app_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.

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.

When a user interacts with your app, your app will receive an Interaction. Your app can receive an interaction in one of two ways:

• Via Interaction Create gateway event
• Via outgoing webhook

These two methods are mutually exclusive; you can only receive Interactions one of the two ways. The INTERACTION_CREATE Gateway 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:

• Slash Commands
• User Commands
• Message Commands
• Message Components
• Modal Components

An explanation of all the fields can be found in our data models.

Now that you've gotten the data from the user, it's time to respond to them.

Interactions--both receiving and responding--are webhooks under the hood. So responding to an Interaction is just like sending a webhook request!

There are a number of ways you can respond to an interaction:

* Only valid for MODAL_SUBMIT and component-based interactions.

** Not available for MODAL_SUBMIT and PING interactions.

Not all message fields are currently supported.

* If you create a callback with the type DEFERRED_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.

import requests

url = "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)

@app.route('/', methods=['POST'])
def my_command():
    if request.json["type"] == 1:
        return jsonify({
            "type": 1
        })

    else:
        return jsonify({
            "type": 4,
            "data": {
                "tts": False,
                "content": "Congrats on sending your command!",
                "embeds": [],
                "allowed_mentions": { "parse": [] }
            }
        })

* Only present if type is LAUNCH_ACTIVITY.

** Only present if type is either CHANNEL_MESSAGE_WITH_SOURCE or UPDATE_MESSAGE.

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:

• PATCH /webhooks/<application_id>/<interaction_token>/messages/@original to edit your initial response to an Interaction
• DELETE /webhooks/<application_id>/<interaction_token>/messages/@original to delete your initial response to an Interaction
• POST /webhooks/<application_id>/<interaction_token> to send a new followup message
• PATCH /webhooks/<application_id>/<interaction_token>/messages/<message_id> to edit a message sent with that token

Interaction tokens are valid for 15 minutes, meaning you can respond to an interaction within that amount of time.

/interactions/{interaction.id}/{interaction.token}/callback

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.

/webhooks/{application.id}/{interaction.token}/messages/@original

Returns the initial Interaction response. Functions the same as Get Webhook Message.

/webhooks/{application.id}/{interaction.token}/messages/@original

Edits the initial Interaction response. Functions the same as Edit Webhook Message.

/webhooks/{application.id}/{interaction.token}/messages/@original

Deletes the initial Interaction response. Returns 204 No Content on success.

/webhooks/{application.id}/{interaction.token}

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 EPHEMERAL message flag 1 << 6 (64) to send a message that only the user can see. You can also use the IS_COMPONENTS_V2 message flag 1 << 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.

/webhooks/{application.id}/{interaction.token}/messages/{message.id}

Returns a followup message for an Interaction. Functions the same as Get Webhook Message.

/webhooks/{application.id}/{interaction.token}/messages/{message.id}

Edits a followup message for an Interaction. Functions the same as Edit Webhook Message.

/webhooks/{application.id}/{interaction.token}/messages/{message.id}

Deletes a followup message for an Interaction. Returns 204 No Content on success.