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_id
, member
and other fields. You can find all the values in our data models.
Data Models and Types
Interaction Object
Interaction Structure
Field | Type | Description |
---|---|---|
id | snowflake | id of the interaction |
application_id | snowflake | id of the application this interaction is for |
type | interaction type | the type of interaction |
data? 1 | interaction data | the command data payload |
guild_id? | snowflake | the guild it was sent from |
channel_id? | snowflake | the channel it was sent from |
member? 2 | guild member object | guild member data for the invoking user, including permissions |
user? | partial user object | user object for the invoking user, if invoked in a DM |
token | string | a continuation token for responding to the interaction |
version | integer | read-only property, always 1 |
message? | message object | for components, the message they were attached to |
1 This is always present on application command and message component interaction types. It is optional for future-proofing against new interaction types.
2 member
is sent when the interaction is invoked in a guild, and user
is sent when invoked in a DM.
Interaction Type
Name | Value |
---|---|
PING | 1 |
APPLICATION_COMMAND | 2 |
MESSAGE_COMPONENT | 3 |
Interaction Data Structure
Field | Type | Description | Interaction Type |
---|---|---|---|
id | snowflake | the ID of the invoked command | Application Command |
name | string | the name of the invoked command | Application Command |
type | integer | the type of the invoked command | Application Command |
resolved? | resolved data | converted users + roles + channels | Application Command |
options? | array of application command interaction data option | the params + values from the user | Application Command |
custom_id? | string | the custom_id of the component | Component |
component_type? | integer | the type of the component | Component |
values? | array of select option values | the values the user selected | Component (Select) |
target_id? | snowflake | id the of user or message targetted by a user or message command | User Command, Message Command |
Resolved Data Structure
Field | Type | Description |
---|---|---|
users? | Map of Snowflakes to partial user objects | the ids and User objects |
members? 1 | Map of Snowflakes to partial member objects | the ids and partial Member objects |
roles? | Map of Snowflakes to role objects | the ids and Role objects |
channels? 2 | Map of Snowflakes to partial channel objects | the ids and partial Channel objects |
messages? | Map of Snowflakes to partial messages objects | the ids and partial Message objects |
1 Partial Member
objects are missing user
, deaf
and mute
fields.
2 Partial Channel
objects only have id
, name
, type
and permissions
fields. Threads will also have thread_metadata
and parent_id
fields.
Message Interaction Object
This is sent on the message object when the message is a response to an Interaction without an existing message.
Message Interaction Structure
Name | Type | Description |
---|---|---|
id | snowflake | id of the interaction |
type | interaction type | the type of interaction |
name | string | the name of the application command |
user | partial user object | the user who invoked the interaction |
Interactions and Bot Users
We're all used to the way that Discord bots have worked for a long time. You make an application in the Dev Portal, 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 our 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 our API (like fetching a guild, or a channel, or updating permissions on a 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 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.
In your application in the Developer Portal, there is a field on the main page called "Interactions Endpoint URL". If you want to receive Interactions via outgoing webhook, you can set your URL in this field. In order for the URL to be valid, you must be prepared for two things ahead of time:
- Your endpoint must be prepared to ACK a
PING
message - 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, we will not validate your URL and it will fail to save.
When you attempt to save a URL, we 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
:
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 app 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:
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.
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
Field | Type | Description |
---|---|---|
type | interaction callback type | the type of response |
data? | interaction callback data | an optional response message |
Interaction Callback Type
Name | Value | Description |
---|---|---|
PONG | 1 | ACK a Ping |
CHANNEL_MESSAGE_WITH_SOURCE | 4 | respond to an interaction with a message |
DEFERRED_CHANNEL_MESSAGE_WITH_SOURCE | 5 | ACK an interaction and edit a response later, the user sees a loading state |
DEFERRED_UPDATE_MESSAGE 1 | 6 | for components, ACK an interaction and edit the original message later; the user does not see a loading state |
UPDATE_MESSAGE 1 | 7 | for components, edit the message the component was attached to |
1 Only valid for component-based interactions
Interaction Callback Data Structure
Not all message fields are currently supported.
Name | Type | Description |
---|---|---|
tts? | boolean | is the response TTS |
content? | string | message content |
embeds? | array of embeds | supports up to 10 embeds |
allowed_mentions? | allowed mentions | allowed mentions object |
flags? | integer | interaction callback data flags |
components? | array of components | message components |
attachments? 1 | array of partial attachment objects | attachment objects with filename and description |
1 See Uploading Files for details.
Interaction Callback Data Flags
Name | Value | Description |
---|---|---|
EPHEMERAL | 1 << 6 | only the user receiving the message can see it |
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:
If you are receiving Interactions over the gateway, you will also need to respond via HTTP. Responses to Interactions are not sent as commands over the gateway.
To respond to a gateway Interaction, make a POST
request like this. 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. This endpoint is only valid for Interactions received over the gateway. Otherwise, respond to the POST
request to issue an initial response.
Followup Messages
Sometimes, your bot 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 InteractionDELETE /webhooks/<application_id>/<interaction_token>/messages/@original
to delete your initial response to an InteractionPOST /webhooks/<application_id>/<interaction_token>
to send a new followup messagePATCH /webhooks/<application_id>/<interaction_token>/messages/<message_id>
to edit a message sent with thattoken
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 is sent with the following headers:
X-Signature-Ed25519
as a signatureX-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:
If you are not properly validating this signature header, we will not allow you to save your interactions URL in the Dev Portal. We will also do automated, routine security checks against your endpoint, including purposefully sending you invalid signatures. If you fail the validation, we will remove your interactions URL in the future and alert you via email and System DM.
Endpoints
Create Interaction Response
POST
/interactions/{interaction.id}/{interaction.token}/callback
Create a response to an Interaction from the gateway. Takes an interaction 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.
Get Original Interaction Response
GET
/webhooks/{application.id}/{interaction.token}/messages/@original
Returns the initial Interaction response. Functions the same as Get Webhook Message.
Edit Original Interaction Response
PATCH
/webhooks/{application.id}/{interaction.token}/messages/@original
Edits the initial Interaction response. Functions the same as Edit Webhook Message.
Delete Original Interaction Response
DELETE
/webhooks/{application.id}/{interaction.token}/messages/@original
Deletes the initial Interaction response. Returns 204
on success.
Create Followup Message
POST
/webhooks/{application.id}/{interaction.token}
Create a followup message for an Interaction. Functions the same as Execute Webhook, but wait
is always true, and flags
can be set to 64
in the body to send an ephemeral message. The thread_id
query parameter is not required (and is furthermore ignored) when using this endpoint for interaction followups.
Get Followup Message
GET
/webhooks/{application.id}/{interaction.token}/messages/{message.id}
Returns a followup message for an Interaction. Functions the same as Get Webhook Message. Does not support ephemeral followups.
Edit Followup Message
PATCH
/webhooks/{application.id}/{interaction.token}/messages/{message.id}
Edits a followup message for an Interaction. Functions the same as Edit Webhook Message. Does not support ephemeral followups.
Delete Followup Message
DELETE
/webhooks/{application.id}/{interaction.token}/messages/{message.id}
Deletes a followup message for an Interaction. Returns 204
on success. Does not support ephemeral followups.