Interactions

An interaction is the message that your application receives when an user uses an application command, triggers a message component, or submits a modal.

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_id, member and other fields. You can find all the values in data models below.

Interaction Object

Interaction Structure

¹ This is always present on non-PING interaction types. It is optional for future-proofing against new interaction types.

² member is sent only when the interaction is triggered in a guild, and user is sent only when triggered in a private channel.

³ The value of the GUILD_INSTALL key may be 0 if the interaction was not triggered in a guild.

⁴ message is sent only when the interaction was triggered from a message component, or the modal submit.

Interaction Type

Interaction Context Type

Interaction Guild Structure

Application Command Data Structure

¹ This can be partial in response to APPLICATION_COMMAND_AUTOCOMPLETE interactions.

² Only present when the application command type is CHAT_INPUT.

³ Only present when the application command type is USER or MESSAGE.

Application Command Data Option Structure

All options have names, and an option can either be a parameter, in which case value will be set, or it can denote a subcommand or group, in which case it will contain another array of options. value and options are mutually exclusive.

¹ For ATTACHMENT options, value will be the attachment ID.

² Only applicable for APPLICATION_COMMAND_AUTOCOMPLETE interactions.

Message Component Data Structure

¹ Only present for select menu components.

Modal Submit Data Structure

Modal Submit Component Data Structure

¹ id does not need to be provided when creating an interaction.

Social Layer SKU Purchase Eligibility Data Structure

Resolved Data Object

Holds extra entities that have been resolved from IDs in an interaction or message.

Resolved Data Structure

¹ Member objects will not include user, deaf and mute fields. The user will be in the users map instead.

² Channel objects will not include permission_overwrites, recipients, icon, application_id, managed and member fields.

Interactions and Bot Users

We're all used to the way that Discord bots have worked for a long time. You make an application, you add a bot user to it, and you copy the token. That token can be used to connect to the Gateway and to make requests against Discord API.

Interactions bring something entirely new to the table: the ability to interact with an application without needing a bot user in the guild. As you read through this documentation, you'll see that bot tokens are only referenced as a helpful alternative to doing a client credentials auth flow. Responding to interactions does not require a bot token.

In many cases, you may still need a bot user. If you need to receive Gateway events, or need to interact with other parts of Discord API (like fetching a guild, or a channel, or updating permissions on an user), those actions are all still tied to having a bot token. However, if you don't need any of those things, you never have to add a bot user to your application at all.

Welcome to the new world.

Receiving an Interaction

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 the Interaction Create Gateway event
• Via outgoing webhook

These two methods are mutually exclusive; you can only receive interactions one of the two ways. The Gateway event will be handled by any shard 0 session, while the webhook method detailed below does not require a connected client.

To use webhooks, you must edit your application and provide a valid interactions_endpoint_url. In order for the URL to be valid, you must be prepared for two things ahead of time:

1. Your endpoint must be prepared to ACK a PING message
2. Your endpoint must be set up to properly handle signature headers—more on that in Security and Authorization

If either of these are not complete, Discord will not validate your URL and it will fail to save.

When you attempt to save a URL, Discord will send a POST request to that URL with a PING payload. The PING payload has a "type": 1. So, to properly ACK the payload, return a 200 response with a payload of "type": 1:

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

You'll also need to properly set up Security and Authorization on your endpoint for the URL to be accepted. Once both of those are complete and your URL has been saved, you can start receiving interactions via webhook! At this point, your bot will no longer receive interactions over the Gateway. If you want to receive them over the Gateway again, simply delete your URL.

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

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!

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

Interaction Response Object

Interaction Response Structure

Interaction Callback Type

Depending on the interaction type, not all callback types may be available. See Allowed by column for interaction types that allow usage of specific callback type.

¹ Only available if the application has access to monetization features. Deprecated: see premium buttons instead.

² Only available if the application has the IFRAME_MODAL flag.

³ Only available if the application has the EMBEDDED flag.

Interaction Callback Message Data Structure

Not all message fields are currently supported.

Interaction Callback Autocomplete Data Structure

Interaction Callback Modal Data Structure

Interaction Callback IFrame Modal Data Structure

IFrame Modal Size

Interaction Callback Social Layer SKU Purchase Eligibility Data

When responding to an interaction received via webhook, your server can simply 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:

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

    return jsonify({
        "type": 4,
        "data": {
            "content": "Congrats on sending your command!",
        }
    })

Optionally, you can also return a 202 status code and response to the interaction with a regular HTTP request, as described below. Note that this does not apply to PING interactions, which must be responded to directly.

If you are receiving interactions over the Gateway, you will also need to respond via HTTP. Note that responses to interactions are not sent as commands over the Gateway.

To respond to an interaction coming from the Gateway, make a POST request like this. interaction_id and interaction_token are both from the received payload.

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

Followup Messages

Sometimes, your application will 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.

Security and Authorization

The internet is a scary place, especially for people hosting open, unauthenticated endpoints. If you are receiving interactions via outgoing webhook, there are some security steps you must take before your app is eligible to receive requests.

Every interaction request is sent with the following headers:

• X-Signature-Ed25519 as a signature
• X-Signature-Timestamp as a timestamp

Using your favorite security library, you must validate the request each time you receive an interaction. If the signature fails validation, respond with a 401 error code. Here's a couple code examples:

const nacl = require("tweetnacl");

// Your public key can be found on your application in the Developer Portal
const PUBLIC_KEY = "APPLICATION_PUBLIC_KEY";

const signature = req.get("X-Signature-Ed25519");
const timestamp = req.get("X-Signature-Timestamp");
const body = req.rawBody; // rawBody is expected to be a string, not raw bytes

const isVerified = nacl.sign.detached.verify(
  Buffer.from(timestamp + body),
  Buffer.from(signature, "hex"),
  Buffer.from(PUBLIC_KEY, "hex"),
);

if (!isVerified) {
  return res.status(401).end("invalid request signature");
}

from nacl.signing import VerifyKey
from nacl.exceptions import BadSignatureError

# Your public key can be found on your application in the Developer Portal
PUBLIC_KEY = 'APPLICATION_PUBLIC_KEY'

verify_key = VerifyKey(bytes.fromhex(PUBLIC_KEY))

signature = request.headers["X-Signature-Ed25519"]
timestamp = request.headers["X-Signature-Timestamp"]
body = request.data.decode("utf-8")

try:
    verify_key.verify(f'{timestamp}{body}'.encode(), bytes.fromhex(signature))
except BadSignatureError:
    abort(401, 'invalid request signature')

If you are not properly validating this signature header, Discord will not allow you to save your interactions URL in the Developer Portal. Discord will also do automated, routine security checks against your endpoint, including purposefully sending you invalid signatures. If you fail the validation, Discord will remove your interactions URL in the future and alert you via email and system DM.

Currently, interactions are sent with a user agent of Discord-Interactions/1.0 (+https://discord.com). However, you should not rely on this for security.

Endpoints

Create a response to an interaction from the Gateway. Accepts an interaction response object. Returns a 204 empty response or the object below depending on the with_response parameter. 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.

Query String Params

Response Body

Interaction Callback Structure

Interaction Callback Resource Structure

¹ Only applicable if type is LAUNCH_ACTIVITY.

² Only applicable if type is CHANNEL_MESSAGE_WITH_SOURCE, or UPDATE_MESSAGE.

Interaction Callback Activity Instance Resource Structure

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

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

Deletes the initial interaction response. Returns a 204 empty response on success.

Create a followup message for an interaction. Functions the same as Execute Webhook, but wait is always true, and flags can have EPHEMERAL flag to send an ephemeral message. The thread_id query parameter is ignored when using this endpoint for interaction followups.

Returns a followup message for an interaction. Functions the same as Get Webhook Message. Does not support ephemeral followups.

Edits a followup message for an interaction. Functions the same as Edit Webhook Message. Does not support ephemeral followups.

Deletes a followup message for an interaction. Functions the same as Delete Webhook Message. Does not support ephemeral followups.

Creates an interaction. Returns a 204 empty response on success. Fires Interaction Create and Interaction Success or Interaction Failure Gateway events.

Files must be attached using a multipart/form-data body (or pre-uploaded to Discord's GCP bucket) as described in Uploading Files.

JSON/Form Params

¹ To create SOCIAL_LAYER_SKU_PURCHASE_ELIGIBILITY interactions, the Check Social Layer SKU Purchase Eligibility endpoint is used instead.

² Only applicable for MESSAGE_COMPONENT interactions.

³ See Uploading Files for details.

Sendable Application Command Data Structure

¹ Only applicable when the application command type is CHAT_INPUT.

² Only applicable when the application command type is USER or MESSAGE.

³ See Uploading Files for details.

Sendable Message Component Data Structure

¹ Either component_type or type must be provided.

² Only applicable for select menu components.

Sendable Modal Submit Data Structure

¹ See Uploading Files for details.

Interaction Creation Location

Interaction Creation Section Name

This value may also be the name of an App Launcher subsection, such as Promoted or Puzzle Games.

Interaction Creation Source Type