Skip to content

Events API

Dispatcher 

Dispatcher()

Callback registry used by the runtime to map event classes to handlers.

Create an empty dispatcher with no registered handlers.

Source code in python/tryx/events.py 
23
24
25
26
    async def on_message(client, event):
        text = event.data.get_text()
        print(f"Received: {text}")
"""

Methods:

on 

on(event_type: type[EventT]) -> Dispatcher

Select an event class and return a decorator-like dispatcher object.

Source code in python/tryx/events.py 
28
29
30
from ._tryx import events  # type: ignore

for name in dir(events):  # type: ignore

__call__ 

__call__(
    func: Callable[..., Awaitable[None]]
    | Callable[..., Any],
) -> Callable[..., Awaitable[None]] | Callable[..., Any]

Register a callback function for the previously selected event class.

The callback receives (client, event) as positional arguments.

Source code in python/tryx/events.py 
32
33
34
35
    if isinstance(obj, type):
        globals()[name] = obj

__all__ = sorted(name for name, obj in globals().items() if isinstance(obj, type))

EvMessage

Main message event.

Attributes

data property 

data: MessageData

Return the normalized message payload.

RETURNS DESCRIPTION
MessageData

MessageData with text, caption, and metadata.

MessageData

Normalized message payload data.

Attributes

message_info property 

message_info: MessageInfo

Return normalized message metadata (id, type, push_name, source).

RETURNS DESCRIPTION
MessageInfo

MessageInfo for this message.

raw_proto property 

raw_proto: Message

Return the raw protobuf message object.

RETURNS DESCRIPTION
Message

The underlying protobuf Message instance.

Methods:

get_extended_text_message 

get_extended_text_message() -> str | None

Extract text from extended text message, or None.

RETURNS DESCRIPTION
str | None

The extended text content, or None.

get_text 

get_text() -> str | None

Extract plain text from the message body.

RETURNS DESCRIPTION
str | None

The message text, or None if not a text message.

EvConnected

Emitted when the session becomes connected.

EvDisconnected

Emitted when the session disconnects.

EvReceipt

Message receipt update event.

Attributes

source property 

source: MessageSource | None

Return the message source, or None if unavailable.

RETURNS DESCRIPTION
MessageSource | None

Optional MessageSource with sender/chat JIDs.

ReceiptType

Receipt status type for incoming receipt events.

ChatPresence

Presence activity state for a chat.

ChatPresenceMedia

Media kind associated with chat presence activity.

EvPresence

Presence update event for a contact.

EvHistorySync

Contains protobuf history sync payload.

Attributes

proto property 

proto: HistorySync

Return the raw HistorySync protobuf.

RETURNS DESCRIPTION
HistorySync

HistorySync proto containing synced messages.

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

Group and Newsletter

  • 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

  • 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.