Event variables

Your code starts with some variables already filled in, like user and server. Which ones you get depends on what started the code.

The tables below list them. Using a variable that is not in the list fails with a "not defined" error. All helper functions in the API reference are there too, unless a section says otherwise.

To read what is on each object, see Objects.

Slash command#

Variable	What it is
`user`	The member who ran the command.
`channel`	The channel it ran in.
`server`	The server.
`interaction`	The slash command interaction.
`command_name`	The command name.
`unix_timestamp`	The current time as a Unix number.
`variables`	Your saved server variables.
Each option	Every option, under its own name. An option `amount` is the variable `amount`.

Only in the post-hook, after the reply is sent:

Variable	What it is
`response`	The reply message.
`response_dm`	The DM reply, when the reply went to DMs.
`response_feedback`	The short "Command executed" note, when the reply went to DMs or another channel.
`view`	Your View, after it finished.
`pre_hook_failed`	`True` when the pre-hook stopped with an error.
`pre_hook_cooldown`	`True` when a cooldown stopped the command.
`pre_hook_error`	The pre-hook's error, if any.

Options win

An option named user replaces the user variable. Name options so they do not clash, like target instead of user.

See How commands run for the order of pre-hook, reply and post-hook.

Text command#

The same as a slash command, with two changes:

message is the message that ran the command. There is no interaction.
Saved variables load first, so a built-in name wins over a variable with the same name.

See Text commands.

Member Join, Leave and Update#

Variable	What it is
`user`	The member.
`server`	The server.
`event`	The raw Discord event.
`unix_timestamp`	The current time.
`old_user`	The member before the change. Leave and Update only.
`added_role`	The role ID, or list of IDs, that was added. Update only.
`removed_role`	The role ID, or list of IDs, that was removed. Update only.

There is no channel and no message. message_id and channel_id are None.

Message#

Runs for every new message. Premium only.

Variable	What it is
`user`	The author.
`message`	The message.
`channel`	Where it was sent.
`message_id`, `channel_id`	Their IDs.
`server`, `event`, `unix_timestamp`	As above.

Skip bots first

This event also runs for bot messages, your own bot's too. Start with a check, or your bot can answer itself forever:

python

if user is None or user.is_bot:
    return

Reaction#

Runs when someone adds or removes one of the emojis you list on the event.

Variable	What it is
`user`	Who reacted.
`channel`	The channel.
`emoji_name`	The emoji, or the custom emoji's name.
`emoji_id`	The custom emoji's ID. `None` for normal emojis.
`action`	`"add"` or `"remove"`.
`message_id`, `channel_id`	The message and its channel.
`server`, `event`, `unix_timestamp`	As above.

There is no message object. Get it with get_message(channel_id, message_id).

Voice Join, Leave and Change#

Variable	What it is
`user`	The member.
`channel`	The channel they joined. On Leave, the channel they left.
`old_channel`	The channel before. `None` on a fresh join.
`server`, `event`, `unix_timestamp`	As above.

Note

Voice Join also runs when someone moves between channels. Check old_channel is None to know it was a fresh join.

Thread#

Runs when a thread is made, changed or deleted.

Variable	What it is
`channel`, `thread`	The thread.
`action`	`"create"`, `"update"` or `"delete"`.
`user`	The thread owner. `None` on delete.
`parent_id`	The channel the thread is in.
`thread_id`	The thread ID.
`event`	The raw Discord event.

There is no server here. Use event.get_guild().

Clock#

Runs when a clock or a repeating job fires. See Scheduling.

Variable	What it is
`custom_id`	The clock or job name.
`metadata`	The data you gave when you set it.
`server`, `event`, `unix_timestamp`	As above.

In the event's custom IDs, list exact names, or end with * to match many, like remind_*.

Vote (top.gg)#

Runs when someone votes for your server on top.gg.

Variable	What it is
`user`	The voter. `None` when they left the server.
`user_id`	The voter's ID. Always set.
`weekend`	`True` for a double-value weekend vote.
`vote_count`	The server's total votes, this one included.
`server`, `event`, `unix_timestamp`	As above.

Runs when someone clicks a saved button or picks from a saved menu. List the component IDs on the event.

Variable	What it is
`interaction`	The click. `interaction.values` holds menu picks.
`user`	Who clicked.
`custom_id`	Which button or menu.
`message`	The message the button is on.
`channel`	The channel.
`message_id`, `channel_id`	Their IDs.
`server`, `unix_timestamp`	As above.

Also here: defer_response, respond_interaction, send_modal, cooldown, require_permission, allowed_roles, banned_roles, allowed_channels, banned_channels.

Answer within 3 seconds

Call defer_response() first, then respond_interaction(...). Or open a form with await send_modal(form) as the first answer. See Interactions.

Runs when someone sends a form. The event's custom IDs list the form IDs.

Variable	What it is
`interaction`	The submit.
`user`	Who sent it.
`custom_id`	The form ID.
`values`	A dict of each field's ID to what they typed.
`channel`, `channel_id`	The channel.
`server`, `unix_timestamp`	As above.

python

answer = values.get("reason", "")

There is no message. The same 3-second rule and helpers as button clicks apply. See Forms.

Autocomplete#

Runs while someone types into a command option that has autocomplete. You return the suggestions.

Variable	What it is
`interaction`	The autocomplete request.
`option`	The option being typed. `option.value` is the text so far.
`server`, `channel_id`, `unix_timestamp`	As above.

There is no user. Reply in under 3 seconds with respond_options. Write await yourself.

python

await respond_options(options, auto_filter=True)

Argument	What it does
`options`	A list of text, or of `AutocompleteChoice(name=..., value=...)`. Only 25 show.
`auto_filter`	`True` keeps only choices that contain what was typed.

python

await respond_options([
    AutocompleteChoice(name="Red team", value="red"),
    AutocompleteChoice(name="Blue team", value="blue"),
])

name is what people see. value is what your command gets. Do not fetch or sleep here: it is too slow.

Your code starts with some variables already filled in, like user and server. Which ones you get depends on what started the code.

The tables below list them. Using a variable that is not in the list fails with a "not defined" error. All helper functions in the API reference are there too, unless a section says otherwise.

To read what is on each object, see Objects.

Slash command#

Variable	What it is
`user`	The member who ran the command.
`channel`	The channel it ran in.
`server`	The server.
`interaction`	The slash command interaction.
`command_name`	The command name.
`unix_timestamp`	The current time as a Unix number.
`variables`	Your saved server variables.
Each option	Every option, under its own name. An option `amount` is the variable `amount`.

Only in the post-hook, after the reply is sent:

Variable	What it is
`response`	The reply message.
`response_dm`	The DM reply, when the reply went to DMs.
`response_feedback`	The short "Command executed" note, when the reply went to DMs or another channel.
`view`	Your View, after it finished.
`pre_hook_failed`	`True` when the pre-hook stopped with an error.
`pre_hook_cooldown`	`True` when a cooldown stopped the command.
`pre_hook_error`	The pre-hook's error, if any.

Options win

An option named user replaces the user variable. Name options so they do not clash, like target instead of user.

See How commands run for the order of pre-hook, reply and post-hook.

Text command#

The same as a slash command, with two changes:

message is the message that ran the command. There is no interaction.
Saved variables load first, so a built-in name wins over a variable with the same name.

See Text commands.

Member Join, Leave and Update#

Variable	What it is
`user`	The member.
`server`	The server.
`event`	The raw Discord event.
`unix_timestamp`	The current time.
`old_user`	The member before the change. Leave and Update only.
`added_role`	The role ID, or list of IDs, that was added. Update only.
`removed_role`	The role ID, or list of IDs, that was removed. Update only.

There is no channel and no message. message_id and channel_id are None.

Message#

Runs for every new message. Premium only.

Variable	What it is
`user`	The author.
`message`	The message.
`channel`	Where it was sent.
`message_id`, `channel_id`	Their IDs.
`server`, `event`, `unix_timestamp`	As above.

Skip bots first

This event also runs for bot messages, your own bot's too. Start with a check, or your bot can answer itself forever:

python

if user is None or user.is_bot:
    return

Reaction#

Runs when someone adds or removes one of the emojis you list on the event.

Variable	What it is
`user`	Who reacted.
`channel`	The channel.
`emoji_name`	The emoji, or the custom emoji's name.
`emoji_id`	The custom emoji's ID. `None` for normal emojis.
`action`	`"add"` or `"remove"`.
`message_id`, `channel_id`	The message and its channel.
`server`, `event`, `unix_timestamp`	As above.

There is no message object. Get it with get_message(channel_id, message_id).

Voice Join, Leave and Change#

Variable	What it is
`user`	The member.
`channel`	The channel they joined. On Leave, the channel they left.
`old_channel`	The channel before. `None` on a fresh join.
`server`, `event`, `unix_timestamp`	As above.

Note

Voice Join also runs when someone moves between channels. Check old_channel is None to know it was a fresh join.

Thread#

Runs when a thread is made, changed or deleted.

Variable	What it is
`channel`, `thread`	The thread.
`action`	`"create"`, `"update"` or `"delete"`.
`user`	The thread owner. `None` on delete.
`parent_id`	The channel the thread is in.
`thread_id`	The thread ID.
`event`	The raw Discord event.

There is no server here. Use event.get_guild().

Clock#

Runs when a clock or a repeating job fires. See Scheduling.

Variable	What it is
`custom_id`	The clock or job name.
`metadata`	The data you gave when you set it.
`server`, `event`, `unix_timestamp`	As above.

In the event's custom IDs, list exact names, or end with * to match many, like remind_*.

Vote (top.gg)#

Runs when someone votes for your server on top.gg.

Variable	What it is
`user`	The voter. `None` when they left the server.
`user_id`	The voter's ID. Always set.
`weekend`	`True` for a double-value weekend vote.
`vote_count`	The server's total votes, this one included.
`server`, `event`, `unix_timestamp`	As above.

Runs when someone clicks a saved button or picks from a saved menu. List the component IDs on the event.

Variable	What it is
`interaction`	The click. `interaction.values` holds menu picks.
`user`	Who clicked.
`custom_id`	Which button or menu.
`message`	The message the button is on.
`channel`	The channel.
`message_id`, `channel_id`	Their IDs.
`server`, `unix_timestamp`	As above.

Also here: defer_response, respond_interaction, send_modal, cooldown, require_permission, allowed_roles, banned_roles, allowed_channels, banned_channels.

Answer within 3 seconds

Call defer_response() first, then respond_interaction(...). Or open a form with await send_modal(form) as the first answer. See Interactions.

Runs when someone sends a form. The event's custom IDs list the form IDs.

Variable	What it is
`interaction`	The submit.
`user`	Who sent it.
`custom_id`	The form ID.
`values`	A dict of each field's ID to what they typed.
`channel`, `channel_id`	The channel.
`server`, `unix_timestamp`	As above.

python

answer = values.get("reason", "")

There is no message. The same 3-second rule and helpers as button clicks apply. See Forms.

Autocomplete#

Runs while someone types into a command option that has autocomplete. You return the suggestions.

Variable	What it is
`interaction`	The autocomplete request.
`option`	The option being typed. `option.value` is the text so far.
`server`, `channel_id`, `unix_timestamp`	As above.

There is no user. Reply in under 3 seconds with respond_options. Write await yourself.

python

await respond_options(options, auto_filter=True)

Argument	What it does
`options`	A list of text, or of `AutocompleteChoice(name=..., value=...)`. Only 25 show.
`auto_filter`	`True` keeps only choices that contain what was typed.

python

await respond_options([
    AutocompleteChoice(name="Red team", value="red"),
    AutocompleteChoice(name="Blue team", value="blue"),
])

name is what people see. value is what your command gets. Do not fetch or sleep here: it is too slow.

Event variables

Slash command#

Text command#

Member Join, Leave and Update#

Message#

Reaction#

Voice Join, Leave and Change#

Thread#

Clock#

Vote (top.gg)#

Button Click / Select Menu Change#

Autocomplete#

Event variables

Slash command#

Text command#

Member Join, Leave and Update#

Message#

Reaction#

Voice Join, Leave and Change#

Thread#

Clock#

Vote (top.gg)#

Button Click / Select Menu Change#

Autocomplete#

Event variables

Slash command#

Text command#

Member Join, Leave and Update#

Message#

Reaction#

Voice Join, Leave and Change#

Thread#

Clock#

Vote (top.gg)#

Button Click / Select Menu Change#

Modal Submit#

Autocomplete#

Event variables

Slash command#

Text command#

Member Join, Leave and Update#

Message#

Reaction#

Voice Join, Leave and Change#

Thread#

Clock#

Vote (top.gg)#

Button Click / Select Menu Change#

Modal Submit#

Autocomplete#