Interactions: handle Discord's signed interaction webhooks (verify, answer PING with PONG, reply inline), respond through the callback endpoint, manage the original response and followups, and register application commands (global and per guild).
The interaction routes (callback, @original, followups) are
authenticated by the interaction token, so they don't need
discord.bot.token. Interaction tokens stay valid for 15 minutes; the
initial response must arrive within 3 seconds.
Values
APPLICATION_COMMAND
APPLICATION_COMMAND: Int 2
APPLICATION_COMMAND_AUTOCOMPLETE
APPLICATION_COMMAND_AUTOCOMPLETE: Int 4
APPLICATION_COMMAND_AUTOCOMPLETE_RESULT
APPLICATION_COMMAND_AUTOCOMPLETE_RESULT: Int 8
CHANNEL_MESSAGE_WITH_SOURCE
CHANNEL_MESSAGE_WITH_SOURCE: Int 4
DEFERRED_CHANNEL_MESSAGE_WITH_SOURCE
DEFERRED_CHANNEL_MESSAGE_WITH_SOURCE: Int 5
DEFERRED_UPDATE_MESSAGE
DEFERRED_UPDATE_MESSAGE: Int 6
EPHEMERAL
EPHEMERAL: Int 64
LAUNCH_ACTIVITY
LAUNCH_ACTIVITY: Int 12
MESSAGE_COMPONENT
MESSAGE_COMPONENT: Int 3
MODAL
MODAL: Int 9
MODAL_SUBMIT
MODAL_SUBMIT: Int 5
PING
PING: Int 1
PONG
PONG: Int 1
UPDATE_MESSAGE
UPDATE_MESSAGE: Int 7
Functions
autocomplete-response
fn (choices: Vec<Map>): Map
Answer an autocomplete interaction with up to 25 choices ([{name, value}], callback type 8).
Example
::discord::interactions/autocomplete-response([{name: "Production", value: "prod"}])
// {type: 8, data: {choices: [{name: "Production", value: "prod"}]}}
bulk-overwrite-global-commands
fn (request: BulkOverwriteGlobalCommandsRequest): Vec<Map>
fn (request: BulkOverwriteGlobalCommandsRequest, opts: Map): Vec<Map>
PUT /applications/{application_id}/commands - Replace the whole set of global commands (commands not listed are deleted). The usual way to sync commands on deploy. Unset fields inside each command are dropped.
Example
::interactions ::discord::interactions
::interactions/bulk-overwrite-global-commands(::interactions/BulkOverwriteGlobalCommandsRequest({
application_id: "1800000000000000000",
commands: [
{name: "ping", description: "Check the bot is alive"},
{name: "report", description: "Generate the daily report"}
]
}))
bulk-overwrite-guild-commands
fn (request: BulkOverwriteGuildCommandsRequest): Vec<Map>
fn (request: BulkOverwriteGuildCommandsRequest, opts: Map): Vec<Map>
PUT /applications/{application_id}/guilds/{guild_id}/commands - Replace every command in one guild.
Example
::interactions ::discord::interactions
commands ::interactions/bulk-overwrite-guild-commands(::interactions/BulkOverwriteGuildCommandsRequest({
application_id: "1800000000000000000",
guild_id: "1000000000000000000",
commands: [{name: "deploy", description: "Start a deploy"}]
}))
map(commands, %.id)
create-followup-message
fn (request: CreateFollowupMessageRequest): Map
fn (request: CreateFollowupMessageRequest, opts: Map): Map
POST /webhooks/{application_id}/{interaction_token} - Send a followup
message. flags: 64 makes it ephemeral. Returns the message.
Example
::interactions ::discord::interactions
followup ::interactions/create-followup-message(::interactions/CreateFollowupMessageRequest({
application_id: "1800000000000000000",
interaction_token: ::hot::ctx/get("discord.interaction.token"),
content: "Only you can see this",
flags: 64
}))
followup.id
create-global-command
fn (request: CreateGlobalCommandRequest): Map
fn (request: CreateGlobalCommandRequest, opts: Map): Map
POST /applications/{application_id}/commands - Create (or overwrite by
name) a global command. Returns 201 for new, 200 for an update. A
CHAT_INPUT command needs a description.
Example
::interactions ::discord::interactions
::interactions/create-global-command(::interactions/CreateGlobalCommandRequest({
application_id: "1800000000000000000",
name: "hello",
description: "Say hello from Hot",
options: [{name: "name", description: "Who to greet", type: 3, required: false}],
contexts: [0, 1]
}))
create-guild-command
fn (request: CreateGuildCommandRequest): Map
fn (request: CreateGuildCommandRequest, opts: Map): Map
POST /applications/{application_id}/guilds/{guild_id}/commands - Create (or overwrite by name) a guild command. Available immediately, which makes guild commands the way to test.
Example
::interactions ::discord::interactions
command ::interactions/create-guild-command(::interactions/CreateGuildCommandRequest({
application_id: "1800000000000000000",
guild_id: "1000000000000000000",
name: "deploy",
description: "Start a deploy",
options: [{name: "env", description: "Target", type: 3, required: true}]
}))
command.id
create-interaction-response
fn (request: CreateInteractionResponseRequest): Any
fn (request: CreateInteractionResponseRequest, opts: Map): Any
POST /interactions/{interaction_id}/{interaction_token}/callback -
Respond out of band instead of inline (within 3 seconds). type is a
callback type (4 message, 5 deferred, 6/7 component update, 8
autocomplete, 9 modal). with_response: true returns the
interaction callback object instead of true. files uploads
attachments with the response.
Example
::interactions ::discord::interactions
::interactions/create-interaction-response(::interactions/CreateInteractionResponseRequest({
interaction_id: "1700000000000000000",
interaction_token: "interaction-token",
type: 4,
data: {content: "Hello from Hot!"}
}))
deferred-response
fn (): Map
fn (ephemeral: Bool): Map
ACK now and show "thinking..." (callback type 5); finish later with
edit-original-interaction-response. Pass true for an ephemeral
reply.
Example
::discord::interactions/deferred-response() // {type: 5}
::discord::interactions/deferred-response(true) // {type: 5, data: {flags: 64}}
deferred-update-response
fn (): Map
For component interactions: ACK without a loading state, edit later (callback type 6).
Example
::discord::interactions/deferred-update-response() // {type: 6}
delete-followup-message
fn (request: DeleteFollowupMessageRequest): Bool
fn (request: DeleteFollowupMessageRequest, opts: Map): Bool
DELETE /webhooks/{application_id}/{interaction_token}/messages/{message_id} - Delete a followup message.
Example
::interactions ::discord::interactions
::interactions/delete-followup-message(::interactions/DeleteFollowupMessageRequest({
application_id: "1800000000000000000",
interaction_token: ::hot::ctx/get("discord.interaction.token"),
message_id: "2500000000000000000"
}))
delete-global-command
fn (request: DeleteGlobalCommandRequest): Bool
fn (request: DeleteGlobalCommandRequest, opts: Map): Bool
DELETE /applications/{application_id}/commands/{command_id} - Delete a global command.
Example
::interactions ::discord::interactions
::interactions/delete-global-command(::interactions/DeleteGlobalCommandRequest({
application_id: "1800000000000000000",
command_id: "2400000000000000000"
}))
delete-guild-command
fn (request: DeleteGuildCommandRequest): Bool
fn (request: DeleteGuildCommandRequest, opts: Map): Bool
DELETE /applications/{application_id}/guilds/{guild_id}/commands/{command_id} - Delete a guild command.
Example
::interactions ::discord::interactions
::interactions/delete-guild-command(::interactions/DeleteGuildCommandRequest({
application_id: "1800000000000000000",
guild_id: "1000000000000000000",
command_id: "2400000000000000000"
}))
delete-original-interaction-response
fn (request: DeleteOriginalInteractionResponseRequest): Bool
fn (request: DeleteOriginalInteractionResponseRequest, opts: Map): Bool
DELETE /webhooks/{application_id}/{interaction_token}/messages/@original
- Delete the initial response.
Example
::interactions ::discord::interactions
::interactions/delete-original-interaction-response(::interactions/DeleteOriginalInteractionResponseRequest({
application_id: "1800000000000000000",
interaction_token: ::hot::ctx/get("discord.interaction.token")
}))
edit-followup-message
fn (request: EditFollowupMessageRequest): Map
fn (request: EditFollowupMessageRequest, opts: Map): Map
PATCH /webhooks/{application_id}/{interaction_token}/messages/{message_id} - Edit a followup message. Only fields you set are sent.
Example
::interactions ::discord::interactions
::interactions/edit-followup-message(::interactions/EditFollowupMessageRequest({
application_id: "1800000000000000000",
interaction_token: ::hot::ctx/get("discord.interaction.token"),
message_id: "2500000000000000000",
content: "Done"
}))
edit-global-command
fn (request: EditGlobalCommandRequest): Map
fn (request: EditGlobalCommandRequest, opts: Map): Map
PATCH /applications/{application_id}/commands/{command_id} - Change a
global command. Only fields you set are sent; clear: ["default_member_permissions"] resets permissions to the default.
Example
::interactions ::discord::interactions
::interactions/edit-global-command(::interactions/EditGlobalCommandRequest({
application_id: "1800000000000000000",
command_id: "2400000000000000000",
description: "Say hello from Hot"
}))
edit-guild-command
fn (request: EditGuildCommandRequest): Map
fn (request: EditGuildCommandRequest, opts: Map): Map
PATCH /applications/{application_id}/guilds/{guild_id}/commands/{command_id} - Change a guild command. Only fields you set are sent.
Example
::interactions ::discord::interactions
::interactions/edit-guild-command(::interactions/EditGuildCommandRequest({
application_id: "1800000000000000000",
guild_id: "1000000000000000000",
command_id: "2400000000000000000",
description: "Start a production deploy"
}))
edit-original-interaction-response
fn (request: EditOriginalInteractionResponseRequest): Map
fn (request: EditOriginalInteractionResponseRequest, opts: Map): Map
PATCH /webhooks/{application_id}/{interaction_token}/messages/@original - Edit the initial response; this is how a deferred (type 5) reply gets its content. Only fields you set are sent.
Example
::interactions ::discord::interactions
::interactions/edit-original-interaction-response(::interactions/EditOriginalInteractionResponseRequest({
application_id: "1800000000000000000",
interaction_token: "interaction-token",
content: "Report ready",
files: [{filename: "report.csv", content: "a,b\n1,2\n"}]
}))
get-followup-message
fn (request: GetFollowupMessageRequest): Map
fn (request: GetFollowupMessageRequest, opts: Map): Map
GET /webhooks/{application_id}/{interaction_token}/messages/{message_id}
- A followup message.
Example
::interactions ::discord::interactions
followup ::interactions/get-followup-message(::interactions/GetFollowupMessageRequest({
application_id: "1800000000000000000",
interaction_token: ::hot::ctx/get("discord.interaction.token"),
message_id: "2500000000000000000"
}))
followup.content
get-global-command
fn (request: GetGlobalCommandRequest): Map
fn (request: GetGlobalCommandRequest, opts: Map): Map
GET /applications/{application_id}/commands/{command_id} - One global command.
Example
::interactions ::discord::interactions
command ::interactions/get-global-command(::interactions/GetGlobalCommandRequest({
application_id: "1800000000000000000",
command_id: "2400000000000000000"
}))
command.version
get-global-commands
fn (request: GetGlobalCommandsRequest): Vec<Map>
fn (request: GetGlobalCommandsRequest, opts: Map): Vec<Map>
GET /applications/{application_id}/commands - Every global command.
Example
::interactions ::discord::interactions
commands ::interactions/get-global-commands(::interactions/GetGlobalCommandsRequest({application_id: "1800000000000000000"}))
map(commands, %.name)
get-guild-command
fn (request: GetGuildCommandRequest): Map
fn (request: GetGuildCommandRequest, opts: Map): Map
GET /applications/{application_id}/guilds/{guild_id}/commands/{command_id} - One guild command.
Example
::interactions ::discord::interactions
command ::interactions/get-guild-command(::interactions/GetGuildCommandRequest({
application_id: "1800000000000000000",
guild_id: "1000000000000000000",
command_id: "2400000000000000000"
}))
command.name
get-guild-command-permissions
fn (request: GetGuildCommandPermissionsRequest): Vec<Map>
fn (request: GetGuildCommandPermissionsRequest, opts: Map): Vec<Map>
GET /applications/{application_id}/guilds/{guild_id}/commands/permissions - Permission overrides for every command in a guild. (Editing them needs a user OAuth2 Bearer token, not a bot token.)
Example
::interactions ::discord::interactions
perms ::interactions/get-guild-command-permissions(::interactions/GetGuildCommandPermissionsRequest({
application_id: "1800000000000000000",
guild_id: "1000000000000000000"
}))
map(perms, %.permissions)
get-guild-commands
fn (request: GetGuildCommandsRequest): Vec<Map>
fn (request: GetGuildCommandsRequest, opts: Map): Vec<Map>
GET /applications/{application_id}/guilds/{guild_id}/commands - The app's commands in one guild.
Example
::interactions ::discord::interactions
commands ::interactions/get-guild-commands(::interactions/GetGuildCommandsRequest({
application_id: "1800000000000000000",
guild_id: "1000000000000000000"
}))
map(commands, %.name)
get-original-interaction-response
fn (request: GetOriginalInteractionResponseRequest): Map
fn (request: GetOriginalInteractionResponseRequest, opts: Map): Map
GET /webhooks/{application_id}/{interaction_token}/messages/@original - The initial response message.
Example
::interactions ::discord::interactions
message ::interactions/get-original-interaction-response(::interactions/GetOriginalInteractionResponseRequest({
application_id: "1800000000000000000",
interaction_token: ::hot::ctx/get("discord.interaction.token")
}))
message.id
handle-request
fn (request: Map, handler: Fn): ::hot::http/HttpResponse
fn (request: Map, handler: Fn, public-key: Str): ::hot::http/HttpResponse
Run an interactions endpoint: verify the request (401 on failure),
answer PING with PONG, and otherwise call handler with the parsed
interaction and return its result as the inline JSON response. The
handler returns a response map such as message-response(...) or
deferred-response(). The 3-arity form takes an explicit public key
instead of discord.public.key.
Example
::interactions ::discord::interactions
on-discord
meta {webhook: {service: "discord", path: "/interactions", method: "POST"}}
fn (request: HttpRequest): HttpResponse {
::interactions/handle-request(request, (interaction) {
cond {
eq(get-in(interaction, ["data", "name"]), "ping") => { ::interactions/message-response({content: "Pong!"}) }
=> { ::interactions/message-response({content: "Unknown command"}, true) }
}
})
}
message-response
fn (data: Map): Map
fn (data: Map, ephemeral: Bool): Map
Reply with a message (callback type 4). data is message content:
{content?, embeds?, components?, allowed_mentions?, flags?, ...}.
The 2-arity form with true makes it ephemeral.
Example
::discord::interactions/message-response({content: "Pong!"})
::discord::interactions/message-response({content: "Only you can see this"}, true)
modal-response
fn (custom-id: Str, title: Str, components: Vec<Map>): Map
Open a modal (callback type 9). components are the modal's
label/text-input components.
Example
modal ::discord::interactions/modal-response("feedback", "Send feedback", [
{type: 18, label: "Comments", component: {type: 4, custom_id: "comments", style: 2}}
])
modal.type // 9
modal.data.custom_id // "feedback"
option-value
fn (interaction: Map, name: Str): Any
Read a slash-command option by name from an interaction
(interaction.data.options, searching one level of subcommands).
Returns null when absent.
Example
interaction {data: {name: "hello", options: [{name: "name", type: 3, value: "Ada"}]}}
who or(::discord::interactions/option-value(interaction, "name"), "world") // => "Ada"
pong
fn (): Map
The PONG response ({type: 1}) for Discord's PING.
Example
::discord::interactions/pong() // {type: 1}
respond
fn (request: Map, verified: Bool, handler: Fn): ::hot::http/HttpResponse
The dispatch step of handle-request after verification. Exposed for
testing.
Example
::discord::interactions/respond({body: {type: 1}}, true, (i) { ::discord::interactions/pong() }).status // 200
::discord::interactions/respond({body: {type: 2}}, false, (i) { ::discord::interactions/pong() }).status // 401
update-message-response
fn (data: Map): Map
For component interactions: edit the message the component is on (callback type 7).
Example
::discord::interactions/update-message-response({content: "Approved", components: []})
// {type: 7, data: {content: "Approved", components: []}}
Types
BulkOverwriteGlobalCommandsRequest
BulkOverwriteGlobalCommandsRequest type {
application_id: Str,
commands: Vec<Map>
}
BulkOverwriteGuildCommandsRequest
BulkOverwriteGuildCommandsRequest type {
application_id: Str,
guild_id: Str,
commands: Vec<Map>
}
CreateFollowupMessageRequest
CreateFollowupMessageRequest type {
application_id: Str,
interaction_token: Str,
content: Str?,
tts: Bool?,
embeds: Vec<Map>?,
allowed_mentions: Map?,
components: Vec<Map>?,
attachments: Vec<Map>?,
flags: Int?,
poll: Map?,
files: Vec<::discord::api/FileUpload>?
}
CreateGlobalCommandRequest
CreateGlobalCommandRequest type {
application_id: Str,
name: Str,
name_localizations: Map?,
description: Str?,
description_localizations: Map?,
options: Vec<Map>?,
default_member_permissions: Str?,
dm_permission: Bool?,
integration_types: Vec<Int>?,
contexts: Vec<Int>?,
type: Int?,
nsfw: Bool?,
handler: Int?
}
CreateGuildCommandRequest
CreateGuildCommandRequest type {
application_id: Str,
guild_id: Str,
name: Str,
name_localizations: Map?,
description: Str?,
description_localizations: Map?,
options: Vec<Map>?,
default_member_permissions: Str?,
type: Int?,
nsfw: Bool?
}
CreateInteractionResponseRequest
CreateInteractionResponseRequest type {
interaction_id: Str,
interaction_token: Str,
type: Int,
data: Map?,
with_response: Bool?,
files: Vec<::discord::api/FileUpload>?
}
DeleteFollowupMessageRequest
DeleteFollowupMessageRequest type {
application_id: Str,
interaction_token: Str,
message_id: Str
}
DeleteGlobalCommandRequest
DeleteGlobalCommandRequest type {
application_id: Str,
command_id: Str
}
DeleteGuildCommandRequest
DeleteGuildCommandRequest type {
application_id: Str,
guild_id: Str,
command_id: Str
}
DeleteOriginalInteractionResponseRequest
DeleteOriginalInteractionResponseRequest type {
application_id: Str,
interaction_token: Str
}
EditFollowupMessageRequest
EditFollowupMessageRequest type {
application_id: Str,
interaction_token: Str,
message_id: Str,
content: Str?,
embeds: Vec<Map>?,
flags: Int?,
allowed_mentions: Map?,
components: Vec<Map>?,
attachments: Vec<Map>?,
poll: Map?,
files: Vec<::discord::api/FileUpload>?,
clear: Vec<Str>?
}
EditGlobalCommandRequest
EditGlobalCommandRequest type {
application_id: Str,
command_id: Str,
name: Str?,
name_localizations: Map?,
description: Str?,
description_localizations: Map?,
options: Vec<Map>?,
default_member_permissions: Str?,
dm_permission: Bool?,
integration_types: Vec<Int>?,
contexts: Vec<Int>?,
nsfw: Bool?,
handler: Int?,
clear: Vec<Str>?
}
EditGuildCommandRequest
EditGuildCommandRequest type {
application_id: Str,
guild_id: Str,
command_id: Str,
name: Str?,
name_localizations: Map?,
description: Str?,
description_localizations: Map?,
options: Vec<Map>?,
default_member_permissions: Str?,
nsfw: Bool?,
clear: Vec<Str>?
}
EditOriginalInteractionResponseRequest
EditOriginalInteractionResponseRequest type {
application_id: Str,
interaction_token: Str,
content: Str?,
embeds: Vec<Map>?,
flags: Int?,
allowed_mentions: Map?,
components: Vec<Map>?,
attachments: Vec<Map>?,
poll: Map?,
files: Vec<::discord::api/FileUpload>?,
clear: Vec<Str>?
}
GetFollowupMessageRequest
GetFollowupMessageRequest type {
application_id: Str,
interaction_token: Str,
message_id: Str
}
GetGlobalCommandRequest
GetGlobalCommandRequest type {
application_id: Str,
command_id: Str
}
GetGlobalCommandsRequest
GetGlobalCommandsRequest type {
application_id: Str,
with_localizations: Bool?
}
GetGuildCommandPermissionsRequest
GetGuildCommandPermissionsRequest type {
application_id: Str,
guild_id: Str
}
GetGuildCommandRequest
GetGuildCommandRequest type {
application_id: Str,
guild_id: Str,
command_id: Str
}
GetGuildCommandsRequest
GetGuildCommandsRequest type {
application_id: Str,
guild_id: Str,
with_localizations: Bool?
}
GetOriginalInteractionResponseRequest
GetOriginalInteractionResponseRequest type {
application_id: Str,
interaction_token: Str
}