Events API¶

This page maps event classes in tryx.events to practical handler strategies.

Dispatcher Contract¶

Dispatcher is used internally by Tryx and by @app.on(EventClass) registration.

@app.on(EvMessage)
async def on_message(client, event):
    ...

Handler model

Keep handlers small, push expensive work into background tasks, and treat incoming event payloads as typed contracts.

Event Taxonomy¶

Lifecycle¶

EvConnected
EvDisconnected
EvLoggedOut
EvStreamReplaced
EvClientOutDated

Pairing¶

EvPairingQrCode
EvPairingCode
EvPairSuccess
EvPairError

Messaging¶

EvMessage
EvReceipt
EvUndecryptableMessage
EvNotification

Sync Actions¶

EvPinUpdate
EvMuteUpdate
EvArchiveUpdate
EvMarkChatAsReadUpdate
EvDeleteChatUpdate
EvDeleteMessageForMeUpdate
EvStarUpdate
EvContactUpdate

Contact, Profile, Presence¶

EvPushNameUpdate
EvSelfPushNameUpdated
EvUserAboutUpdate
EvPictureUpdate
EvPresence
EvChatPresence
EvContactUpdated
EvContactNumberChanged
EvContactSyncRequested

Device and Business¶

EvDeviceListUpdate
EvBusinessStatusUpdate

EvJoinedGroup
EvGroupInfoUpdate
EvGroupUpdate
EvNewsletterLiveUpdate

Event-to-Namespace Mapping¶

Event family	Namespace actions usually paired
Messaging	Chat Actions, Contact, root send methods
Group updates	Groups, Community
Newsletter updates	Newsletter, Polls
Presence updates	Presence, Chatstate
Profile updates	Profile, Privacy

Payload Discipline¶

RecommendedAvoid

Read typed fields from event.data.
Guard optional values (None) before usage.
Log identity metadata (chat_jid, sender, message_id) for observability.

Parsing raw protobuf bytes when typed fields already exist.
Long blocking work inside handler coroutine.
Assuming strict order between unrelated event classes.

Example: Safe Event Router¶

from tryx.events import EvMessage, EvPresence


@app.on(EvMessage)
async def on_message(client, event):
    chat = event.data.message_info.source.chat
    text = event.data.get_text() or ""
    if text == "/ping":
        await client.send_text(chat, "pong", quoted=event)


@app.on(EvPresence)
async def on_presence(client, event):
    # keep side effects minimal; enqueue heavy processing
    pass

Enum-like Support Types¶

Common reason/state classes used by event payloads:

TempBanReason
ReceiptType
UnavailableType
DecryptFailMode
ChatPresence, ChatPresenceMedia
DeviceListUpdateType
BusinessStatusUpdateType
GroupNotificationAction

Reliability

Treat sync events as convergence signals, not anomalies. They are expected in multi-device behavior.