Dokumentation / Developers / Referenz / Event payloads

GeneratedSDK 0.10.120 events

Event payloads

Every event a plugin can subscribe to, with each payload field, its type and an example.

Subscribe with @plugin.on_event("name"). Every field is optional at the type level, so read with event.get("field"). Snowflakes are strings. Timestamps are ISO 8601.

`channel_create`

ChannelCreate7 fields

Payload for @plugin.on_event("channel_create") handlers.

Feld	Typ	Bedeutung
`channel_id`	str
`id`	str	alias for channel_id
`name`	str
`type`	int	Discord channel type
`category_id`	Optional[str]
`position`	Optional[int]
`guild_id`	Optional[str]

`channel_delete`

ChannelDelete7 fields

Payload for @plugin.on_event("channel_delete") handlers.

Feld	Typ	Bedeutung
`channel_id`	str
`id`	str
`name`	str
`type`	int
`category_id`	Optional[str]
`position`	Optional[int]
`guild_id`	Optional[str]

`channel_update`

ChannelUpdate8 fields

Payload for @plugin.on_event("channel_update") handlers. Top-level fields are the current state. The previous state, when available, lives under the before_* keys.

Feld	Typ	Bedeutung
`channel_id`	str
`id`	str
`name`	str
`before_name`	Optional[str]
`type`	int
`category_id`	Optional[str]
`position`	Optional[int]
`guild_id`	Optional[str]

`interaction_create`

InteractionCreate11 fields

Payload for @plugin.on_event("interaction_create") handlers. Fired when a user clicks a button, submits a modal, or invokes a slash command. For slash commands you usually want @plugin.on_slash_command("name") instead — it receives the same payload but only fires for the matching command.

Feld	Typ	Bedeutung
`interaction_id`	str
`type`	int	Discord interaction type (2=slash, 3=component, 5=modal)
`interaction_type`	int	alias used by the testing harness
`channel_id`	Optional[str]
`user_id`	Optional[str]
`user_name`	Optional[str]
`command_name`	Optional[str]	for slash commands
`command_type`	Optional[int]	for slash commands
`custom_id`	Optional[str]	for component/modal interactions
`modal_values`	dict	for modal submissions
`guild_id`	Optional[str]

Example payload

{
  "channel_id": "999000000000000010",
  "command_name": "test",
  "command_type": 1,
  "interaction_id": "999000000000000099",
  "interaction_type": 2,
  "options": [],
  "user_id": "999000000000000020",
  "user_name": "test_user"
}

`member_join`

MemberJoin10 fields

Payload for @plugin.on_event("member_join") handlers.

Feld	Typ	Bedeutung
`user_id`	str
`username`	str
`display_name`	Optional[str]
`bot`	bool
`joined_at`	Optional[str]	ISO-8601 timestamp
`roles`	list[str]	role IDs as strings
`nick`	Optional[str]
`guild_id`	Optional[str]
`guild_name`	Optional[str]
`member_count`	int	server's total member count after join

Example payload

{
  "bot": false,
  "display_name": "Test User",
  "joined_at": "",
  "nick": null,
  "roles": [],
  "user_id": "999000000000000020",
  "username": "test_user"
}

`member_leave`

MemberLeave8 fields

Payload for @plugin.on_event("member_leave") handlers. Fired for both voluntary leaves and kicks/bans (Discord doesn't distinguish in the gateway event).

Feld	Typ	Bedeutung
`user_id`	str
`username`	str
`display_name`	Optional[str]
`bot`	bool
`joined_at`	Optional[str]
`roles`	list[str]
`nick`	Optional[str]
`guild_id`	Optional[str]

Example payload

{
  "bot": false,
  "display_name": "Test User",
  "user_id": "999000000000000020",
  "username": "test_user"
}

`member_update`

MemberUpdate9 fields

Payload for @plugin.on_event("member_update") handlers. Fired on nick change, role change, timeout, avatar change. The new state is in the top-level fields; before_roles carries the prior role set.

Feld	Typ	Bedeutung
`user_id`	str
`username`	str
`display_name`	Optional[str]
`bot`	bool
`roles`	list[str]	current roles
`before_roles`	list[str]	roles before this update
`nick`	Optional[str]
`before_nick`	Optional[str]
`guild_id`	Optional[str]

`message_create`

MessageCreate15 fields

Payload for @plugin.on_event("message_create") handlers. Fired when a message is sent in a server channel the bot can see.

Feld	Typ	Bedeutung
`message_id`	str	snowflake of the message
`channel_id`	str	snowflake of the channel
`channel_name`	Optional[str]	channel display name (e.g. "general")
`author_id`	str	snowflake of the author user
`author_name`	Optional[str]	author's Discord username
`author_bot`	bool	True if the author is a bot
`content`	str	message body text (may be empty if only embeds/attachments)
`created_at`	Optional[str]	ISO-8601 timestamp
`embed_count`	int	number of embeds attached
`attachment_count`	int	number of file attachments
`mention_count`	int	number of users mentioned
`reference_message_id`	Optional[str]	Present only on replies; absent for normal messages.
`author_username`	Optional[str]	Aliases / extras populated by some surfaces (testing harness, older gateway).
`guild_id`	Optional[str]
`timestamp`	Optional[str]

Example payload

{
  "attachment_count": 0,
  "author_bot": false,
  "author_id": "999000000000000020",
  "author_name": "test_user",
  "channel_id": "999000000000000010",
  "channel_name": "general",
  "content": "hello from replay",
  "created_at": "",
  "embed_count": 0,
  "mention_count": 0,
  "message_id": "999000000000000001"
}

`message_delete`

MessageDelete5 fields

Payload for @plugin.on_event("message_delete") handlers. Note: content is only present when the message was in the gateway cache at deletion time. Treat it as best-effort.

Feld	Typ	Bedeutung
`message_id`	str
`channel_id`	str
`author_id`	Optional[str]
`content`	Optional[str]
`guild_id`	Optional[str]

Example payload

{
  "attachment_count": 0,
  "author_id": "999000000000000020",
  "channel_id": "999000000000000010",
  "content": "",
  "embed_count": 0,
  "mention_count": 0,
  "message_id": "999000000000000001"
}

`message_edit`

MessageEdit8 fields

Payload for @plugin.on_event("message_edit") handlers.

Feld	Typ	Bedeutung
`message_id`	str
`channel_id`	str
`author_id`	Optional[str]
`content`	str	post-edit content
`embed_count`	int
`attachment_count`	int
`mention_count`	int
`guild_id`	Optional[str]

Example payload

{
  "attachment_count": 0,
  "author_id": "999000000000000020",
  "channel_id": "999000000000000010",
  "content": "edited from replay",
  "embed_count": 0,
  "mention_count": 0,
  "message_id": "999000000000000001"
}

`reaction_add`

ReactionAdd6 fields

Payload for @plugin.on_event("reaction_add") handlers.

Feld	Typ	Bedeutung
`message_id`	str
`channel_id`	str
`user_id`	str
`emoji`	str	``"👍"`` or ``"<a:name:id>"`` for custom
`user_bot`	bool
`guild_id`	Optional[str]

Example payload

{
  "channel_id": "999000000000000010",
  "emoji": "wave",
  "guild_id": "999000000000000000",
  "message_id": "999000000000000001",
  "user_bot": false,
  "user_id": "999000000000000020"
}

`reaction_remove`

ReactionRemove6 fields

Payload for @plugin.on_event("reaction_remove") handlers.

Feld	Typ	Bedeutung
`message_id`	str
`channel_id`	str
`user_id`	str
`emoji`	str
`user_bot`	bool
`guild_id`	Optional[str]

`role_create`

RoleCreate9 fields

Payload for @plugin.on_event("role_create") handlers.

Feld	Typ	Bedeutung
`role_id`	str
`id`	str
`name`	str
`color`	int	RGB integer
`position`	int
`permissions`	str	Discord permission integer as string (precision-safe)
`managed`	bool
`mentionable`	bool
`guild_id`	Optional[str]

`role_delete`

RoleDelete9 fields

Payload for @plugin.on_event("role_delete") handlers.

Feld	Typ	Bedeutung
`role_id`	str
`id`	str
`name`	str
`color`	int
`position`	int
`permissions`	str
`managed`	bool
`mentionable`	bool
`guild_id`	Optional[str]

`role_update`

RoleUpdate10 fields

Payload for @plugin.on_event("role_update") handlers.

Feld	Typ	Bedeutung
`role_id`	str
`id`	str
`name`	str
`before_name`	Optional[str]
`color`	int
`position`	int
`permissions`	str
`managed`	bool
`mentionable`	bool
`guild_id`	Optional[str]

`voice_state_update`

VoiceStateUpdate16 fields

Payload for @plugin.on_event("voice_state_update") handlers. Fired on join voice, leave voice, channel switch, mute/deafen, stream start/stop. The transition is encoded as before_channel_id (where they were, None = nowhere) and after_channel_id (where they are now, None = left voice entirely).

Feld	Typ	Bedeutung
`user_id`	str
`username`	Optional[str]
`bot`	bool
`member_bot`	bool
`before_channel_id`	Optional[str]
`before_channel_name`	Optional[str]
`after_channel_id`	Optional[str]
`after_channel_name`	Optional[str]
`before_self_stream`	bool
`after_self_stream`	bool
`self_mute`	bool
`self_deaf`	bool
`self_stream`	bool
`self_video`	bool
`guild_id`	Optional[str]
`channel_id`	Optional[str]	Convenience alias used by some handlers; same as after_channel_id.

Example payload

{
  "after_channel_id": "999000000000000050",
  "after_channel_name": "Voice Lobby",
  "before_channel_id": null,
  "before_channel_name": null,
  "bot": false,
  "self_deaf": false,
  "self_mute": false,
  "self_stream": false,
  "self_video": false,
  "user_id": "999000000000000020",
  "username": "test_user"
}

Also delivered

These events reach @plugin.on_event handlers too. They do not have a typed payload class in the SDK yet; their fields are listed under Build, Discord events.

guild_joinguild_removereaction_clearthread_create

Discord events in the Build guide

YourBot docs Reference tables are generated from the code that is running. Ask in Discord Suggest a correction