Skip to content

Client API Gateway

Tryx 

Tryx(backend: BackendBase | FfiStoreProtocol | StoreBase)

Main automation runtime controller.

Use this class to register event handlers and start the connection lifecycle.

Accepts any of the 3 storage backend tiers:

  • SqliteStore — built-in SQLite backend
  • FfiStoreProtocol — native FFI backend (e.g. tryx-store-postgres)
  • StoreBase subclass — pure Python custom backend

Create a Tryx runtime with the given storage backend.

PARAMETER DESCRIPTION
backend

Storage backend (SqliteStore, FfiStoreProtocol, or StoreBase).

TYPE: BackendBase | FfiStoreProtocol | StoreBase

Example::

from tryx.backend import SqliteStore
from tryx.client import Tryx

app = Tryx(SqliteStore('session.db'))

Methods:

get_client 

get_client() -> TryxClient

Return the connected client facade.

RAISES DESCRIPTION
RuntimeError

If the client is not yet running.

Example::

client = app.get_client()
await client.send_text(to=JID('123', 's.whatsapp.net'), text='hi')

on 

on(
    event_type: type[EventT],
) -> Callable[
    [Callable[[TryxClient, EventT], Awaitable[None]]],
    Callable[[TryxClient, EventT], Awaitable[None]],
]

Decorator to register an async event handler.

Example::

@app.on(EvMessage)
async def handler(client: TryxClient, event: EvMessage) -> None:
    text = event.data.get_text()
    chat = event.data.message_info.source.chat
    await client.send_text(to=chat, text=text)

run 

run() -> Awaitable[None]

Start the client in async mode.

Example::

asyncio.run(app.run())

run_blocking 

run_blocking() -> None

Start the client and block until it exits.

Example::

app.run_blocking()

TryxClient is the runtime facade passed to every handler, and it exposes a root messaging surface plus 12 namespace clients.

How to read this section

  1. Start with this gateway page.
  2. Open the namespace page that matches your task.
  3. Jump to Events API for event contracts and Types API for enum/value-object constraints.

Client Topology

flowchart TD
    A[TryxClient] --> B[Root send/download/upload methods]
    A --> C[contact]
    A --> D[chat_actions]
    A --> E[community]
    A --> F[newsletter]
    A --> G[groups]
    A --> H[status]
    A --> I[chatstate]
    A --> J[blocking]
    A --> K[polls]
    A --> L[presence]
    A --> M[privacy]
    A --> N[profile]

Namespace Router

Contact Find users, check registration state, fetch profile pictures

Chat Actions Archive, pin, mute, read-state, edit/revoke/react

Groups Group lifecycle, membership approval, participant admin

Community Community creation, subgroup management

Newsletter Channel subscription, posting, follower management

Status Status updates with privacy controls

Chatstate Typing and recording indicators

Blocking Block/unblock and blocklist queries

Polls Encrypted poll creation and vote aggregation

Presence Online/offline presence and subscriptions

Privacy Privacy settings and disallowed lists

Profile Push name, status text, profile picture

Root Transport Methods

These methods stay on TryxClient directly because they are cross-domain primitives.

Method Purpose Typical Usage
is_connected() Connection health check Guard before sends
download_media(message) Download media blob Save image/audio/document
upload_file(path, media_type) Upload file for later use Status media workflows
upload(data, media_type) Upload in-memory bytes Transform pipelines
send_message(to, message) Raw protobuf send Advanced custom payloads
send_text(...) Text helper Most command handlers
send_photo(...) Image helper Replies with screenshots
send_document(...) File helper Reports, exports
send_audio(...) Audio helper Voice notes / TTS
send_video(...) Video helper Clips, demos
send_gif(...) GIF helper Motion responses
send_sticker(...) Sticker helper Lightweight reactions
request_media_reupload(...) Recover stale media Retry failed downloads

Reconnect-safe pattern

Avoid caching TryxClient on global module state across runtime restarts. Always use the client object injected in the current handler call.

Practical Flow by Goal

Use root send methods + chat_actions + chatstate.

  1. Parse incoming event.
  2. Signal typing with client.chatstate.send_composing(chat).
  3. Send reply with client.send_text(...).
  4. Optional message edit/revoke via client.chat_actions.

Use groups, blocking, privacy.

  1. Resolve sender via Types API.
  2. Apply participant actions (promote, remove, approve request).
  3. Enforce policy with blocklist/privacy settings.

Use status, newsletter, polls.

  1. Upload content or build text payload.
  2. Publish status/newsletter message.
  3. Track engagement using polls and reactions.

Cross-References