Event Reference

Events are received in listeners using event_listener().

Event names are case-sensitive and uses underscores (_) for spaces.

APPLICATION_COMMAND_PERMISSIONS_UPDATE

Received when an application command’s permissions are updated. The inner payload is an GuildApplicationCommandPermissions object.

AUTO_MODERATION_ACTION_EXECUTION

Received when a rule is triggered and an action is executed (e.g. when a message is blocked).

class discord.events.AutoModerationActionExecutionEvent

Received when a rule is triggered and an action is executed (e.g. when a message is blocked).

action: AutoModerationAction

Action which was executed

alert_system_message_id: Optional[Snowflake]

ID of any system auto moderation messages posted as a result of this action.

Note

alert_system_message_id will not exist if this event does not correspond to an action with type AutoModerationActionType.

channel_id: Optional[Snowflake]

ID of the channel in which user content was posted

content: str

User-generated text content

Note

MESSAGE_CONTENT gateway intent is required to receive the content and matched_content fields.

guild_id: Snowflake

ID of the guild in which action was executed

matched_content: Nullable[str]

Substring in content that triggered the rule.

Note

MESSAGE_CONTENT gateway intent is required to receive the content and matched_content fields.

matched_keyword: Nullable[str]

Word or phrase configured in the rule that triggered the rule

message_id: Optional[Snowflake]

ID of any user message which content belongs to.

Note

message_id will not exist if message was blocked by Auto Moderation or content was not part of any message.

rule_id: Snowflake

ID of the rule which action belongs to

rule_trigger_type: AutoModerationRuleTriggerType

Trigger type of rule which was triggered

user_id: Snowflake

ID of the user which generated the content which triggered the rule

AUTO_MODERATION_RULE_CREATE

Received when a rule is created. The inner payload is an AutoModerationRule object.

AUTO_MODERATION_RULE_DELETE

Received when a rule is deleted. The inner payload is an AutoModerationRule object.

AUTO_MODERATION_RULE_UPDATE

Received when a rule is updated. The inner payload is an AutoModerationRule object.

CHANNEL_CREATE

Received when a new guild channel is created, relevant to the current user. The inner payload is a Channel object.

CHANNEL_DELETE

Received when a channel relevant to the current user is deleted. The inner payload is a Channel object.

CHANNEL_INFO

Includes ephemeral data for channels in a guild. Received in response to request_channel_info().

class discord.events.ChannelInfoEvent

channels: list[ChannelInfoChannel]

Ephemeral data for channels in the guild.

guild_id: Snowflake

The guild ID.

CHANNEL_PINS_UPDATE

Received when a message is pinned or unpinned in a text channel. This is not sent when a pinned message is deleted.

class discord.events.ChannelPinsUpdateEvent

channel_id: Snowflake

ID of the channel.

guild_id: Optional[Snowflake]

ID of the guild.

last_pin_timestamp: Optional[Nullable[ISO8601Timestamp]]

Time at which the most recent pinned message was pinned.

CHANNEL_UPDATE

Received when a channel is updated. The inner payload is a Channel object. This is not sent when the last_message_id field is altered. To keep track of the last_message_id changes, you must listen for MESSAGE_CREATE events (or THREAD_CREATE events for GUILD_FORUM and GUILD_MEDIA channels).

Note

This event may reference roles or guild members that no longer exist in the guild.

READY

Dispatched when the client has completed the initial handshake with the gateway (for new sessions).

class discord.events.ReadyEvent

application: Application

Contains id and flags

guilds: list[UnavailableGuild]

Guilds the user is in

resume_gateway_url: str

Gateway URL for resuming connections

session_id: str

Used for resuming connections

shard: Optional[list[int, int]]

Shard information associated with this session, if sent when identifying

user: User

Information about the user including email

v: int

API version

THREAD_CREATE

Received when a thread is created, relevant to the current user, or when the current user is added to a thread. The inner payload is a Channel object.

• When a thread is created, includes an additional newly_created boolean field.

• When being added to an existing private thread, includes a member object.

class discord.events.ThreadCreateEvent

newly_created: Optional[bool]

THREAD_DELETE

Received when a thread relevant to the current user is deleted. The inner payload is a subset of the Channel object, containing just the id, guild_id, parent_id, and type fields.

THREAD_LIST_SYNC

Received when the current user gains access to a channel.

class discord.events.ThreadListSyncEvent

channel_ids: Optional[list[Snowflake]]

Parent channel IDs whose threads are being synced. If omitted, then threads were synced for the entire guild. This array may contain channel IDs that have no active threads as well, so you know to clear that data.

guild_id: Snowflake

ID of the guild.

members: list[ThreadMember]

All thread member objects from the synced threads for the current user, indicating which threads the current user has been added to.

threads: list[Channel]

All active threads in the given channels that the current user can access.

THREAD_MEMBERS_UPDATE

Received when anyone is added to or removed from a thread. If the current user does not have the GUILD_MEMBERS gateway intent, then this event will only be sent if the current user was added to or removed from the thread.

class discord.events.ThreadMembersUpdateEvent

added_members: Optional[list[ThreadMember]]

Users who were added to the thread.

Note

In this gateway event, the thread member objects will also include the guild member and nullable presence objects for each added thread member.

guild_id: Snowflake

ID of the guild.

id: Snowflake

ID of the thread.

member_count: int

Approximate number of members in the thread, capped at 50.

removed_member_ids: Optional[list[Snowflake]]

ID of the users who were removed from the thread.

THREAD_UPDATE

Received when a thread is updated. The inner payload is a Channel object. This is not sent when the last_message_id is altered. To keep track of the last_message_id changes, you must listen for MESSAGE_CREATE events.

VOICE_CHANNEL_START_TIME_UPDATE

Received when the voice channel start time changes.

class discord.events.VoiceChannelStartTimeUpdateEvent

guild_id: Snowflake

The guild ID.

id: Snowflake

The channel ID.

voice_start_time: Optional[Nullable[int]]

Unix timestamp (in seconds) of when the voice session started.

VOICE_CHANNEL_STATUS_UPDATE

Received when the voice channel status changes.

class discord.events.VoiceChannelStatusUpdateEvent

guild_id: Snowflake

The guild ID.

id: Snowflake

The channel ID.

status: Nullable[str]

The new voice channel status.