alterself Gateway Events: Registration and Reference

alterself connects to the Discord gateway over a persistent WebSocket and receives a continuous stream of JSON payloads describing everything that happens in Discord, including messages, reactions, guild changes, voice state transitions, and more. For each payload, alterself looks up the event name, builds the appropriate model objects (such as Message, Guild, or User), and calls every registered listener in the order it was added. You register listeners using decorators or the manual registration API, and alterself takes care of the rest.

Registering Listeners

alterself offers three styles of listener registration so you can choose whichever fits your code structure best.

`@bot.on_event`: register by function name

Decorate a coroutine whose name starts with on_. alterself strips the on_ prefix and matches the remainder (case-insensitively) against gateway event names:

@bot.on_event
async def on_ready():
    print(f"Logged in as {bot.me.username}#{bot.me.discriminator}")

@bot.on_event
async def on_message_create(message):
    print(f"[{message.channel_id}] {message.author.username}: {message.content}")

`@bot.listen(event_name)`: explicit name

Use this decorator when you want to give the function a different name, or when you need multiple handlers for the same event in the same scope:

@bot.listen("MESSAGE_CREATE")
async def log_messages(message):
    print(f"Message in {message.channel_id}: {message.content}")

@bot.listen("message_create")   # case-insensitive
async def react_to_keywords(message):
    if "hello" in message.content.lower():
        print("Greeting detected!")

`bot.add_listener` / `bot.remove_listener`: manual registration

Register and deregister listeners programmatically, which is useful for testing, conditional feature flags, or dynamic plugin systems:

async def on_typing(typing_event):
    print(f"User {typing_event.user_id} is typing in {typing_event.channel_id}")

bot.add_listener("TYPING_START", on_typing)

# Later, remove the listener
bot.remove_listener("TYPING_START", on_typing)

Multiple listeners can be registered for the same event. alterself calls them all concurrently using asyncio.gather, so a slow listener does not block others.

Event Reference

Connection

Event	Handler signature	Description
`READY`	`on_ready()`	The gateway session is established and the initial state is available. `bot.me` is populated.
`RESUMED`	`on_resumed()`	A dropped connection was successfully resumed. Previously dispatched events were not replayed.

Messages

Event	Handler signature	Description
`MESSAGE_CREATE`	`on_message_create(message: Message)`	A message was created in a visible channel
`MESSAGE_UPDATE`	`on_message_update(message: Message \| None)`	A message was edited; `None` if the message is not in the cache
`MESSAGE_DELETE`	`on_message_delete(message_id: int, channel_id: int, guild_id: int \| None)`	A single message was deleted
`MESSAGE_DELETE_BULK`	`on_message_delete_bulk(message_ids: list[int], channel_id: int, guild_id: int \| None)`	Multiple messages were bulk-deleted
`MESSAGE_REACTION_ADD`	`on_message_reaction_add(reaction: dict)`	A reaction was added to a message
`MESSAGE_REACTION_REMOVE`	`on_message_reaction_remove(reaction: dict)`	A reaction was removed from a message

Guilds

Event	Handler signature	Description
`GUILD_CREATE`	`on_guild_create(guild: Guild)`	A guild became available (login, join, or reconnect)
`GUILD_UPDATE`	`on_guild_update(guild: Guild)`	A guild’s settings were changed
`GUILD_DELETE`	`on_guild_delete(guild_id: int)`	You left a guild or it became unavailable
`GUILD_MEMBER_ADD`	`on_guild_member_add(member: Member)`	A user joined a guild
`GUILD_MEMBER_REMOVE`	`on_guild_member_remove(user: User, guild_id: int)`	A user left or was removed from a guild
`GUILD_MEMBER_UPDATE`	`on_guild_member_update(member: Member)`	A guild member’s roles, nickname, or other attributes changed

Channels

Event	Handler signature	Description
`CHANNEL_CREATE`	`on_channel_create(channel: Channel)`	A new channel was created in a guild
`CHANNEL_UPDATE`	`on_channel_update(channel: Channel)`	A channel’s settings were updated
`CHANNEL_DELETE`	`on_channel_delete(channel: Channel)`	A channel was deleted
`THREAD_CREATE`	`on_thread_create(thread: Thread)`	A new thread was created or you were added to one
`THREAD_UPDATE`	`on_thread_update(thread: Thread)`	A thread’s metadata changed
`THREAD_DELETE`	`on_thread_delete(thread_id: int, channel_id: int, guild_id: int)`	A thread was deleted

Presence and Typing

Event	Handler signature	Description
`TYPING_START`	`on_typing_start(event: dict)`	A user started typing in a channel
`PRESENCE_UPDATE`	`on_presence_update(presence: dict)`	A user’s online status or activity changed

Relationships

Event	Handler signature	Description
`RELATIONSHIP_ADD`	`on_relationship_add(relationship: dict)`	A friend request was received or accepted, or a user was blocked
`RELATIONSHIP_REMOVE`	`on_relationship_remove(relationship: dict)`	A friend was removed or a block was lifted

Voice

Event	Handler signature	Description
`VOICE_STATE_UPDATE`	`on_voice_state_update(state: dict)`	A user joined, moved, or left a voice channel, or their mute/deafen state changed
`VOICE_SERVER_UPDATE`	`on_voice_server_update(event: dict)`	The voice server endpoint for a guild changed

Raw Event Access

If you need the unprocessed gateway payload before alterself parses it into model objects, listen for the special RAW event. Your handler receives the full payload dictionary exactly as it arrived from Discord:

@bot.listen("RAW")
async def on_raw(payload: dict):
    event_type = payload.get("t")
    data       = payload.get("d")
    print(f"Raw event: {event_type} → {data}")

Raw payloads contain field names and structures defined by the Discord API, which can change without notice. Prefer the typed model objects whenever possible, and fall back to raw access only when you need a field that alterself does not yet expose.

Complete Examples

import logging
import alterself

bot = alterself.Client(token="...", prefix=".")

@bot.on_event
async def on_ready():
    await bot.change_presence(
        status="idle",
        activities=[alterself.watching("everything")],
        afk=False,
    )
    logging.info("Ready as %s (ID: %s)", bot.me.username, bot.me.id)

bot.run(log_level=logging.INFO)

import alterself

bot = alterself.Client(token="...", prefix=".")

@bot.on_event
async def on_message_create(message):
    # Only react to your own messages
    if message.author.id != bot.me.id:
        return

    if message.content.lower() == "ping":
        await bot.http.edit_message(
            message.channel_id,
            message.id,
            content=f"Pong! ({bot.latency * 1000:.1f} ms)",
        )

bot.run()

Get Started

Core Concepts

Guides

alterself Gateway Events: Registration and Reference

Registering Listeners

`@bot.on_event`: register by function name

`@bot.listen(event_name)`: explicit name

`bot.add_listener` / `bot.remove_listener`: manual registration

Event Reference

Connection

Messages

Guilds

Channels

Presence and Typing

Relationships

Voice

Raw Event Access

Complete Examples

​Registering Listeners

​@bot.on_event: register by function name

​@bot.listen(event_name): explicit name

​bot.add_listener / bot.remove_listener: manual registration

​Event Reference

​Connection

​Messages

​Guilds

​Channels

​Presence and Typing

​Relationships

​Voice

​Raw Event Access

​Complete Examples

Registering Listeners

`@bot.on_event`: register by function name

`@bot.listen(event_name)`: explicit name

`bot.add_listener` / `bot.remove_listener`: manual registration

Event Reference

Connection

Messages

Guilds

Channels

Presence and Typing

Relationships

Voice

Raw Event Access

Complete Examples