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: Int 9
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)
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
}