Presence

Before you start: complete Messaging. Use its channel and chat objects, with credentials granting read access to chat. Register listeners before connecting; request a listing only once the channel is connected.

Presence describes connections, not unique people. A user with three connections appears three times, each with its own connection_id.

1. Register a listener and hold presence interest

from useceleris_client import PresenceEvent


def show_presence(event: PresenceEvent) -> None:
    print("Joined" if event.joined else "Left", event.token_reference, event.connection_id)


stop_presence = chat.on_presence(show_presence)
presence_subscription = chat.subscribe_presence()

on_presence() registers a local listener; subscribe_presence() requests notifications. Keep both while you need them. event.joined is a bool, event.timestamp an int in Unix milliseconds, and the identifiers are strings.

A presence subscription also joins the segment for messages. Cancelling presence does not by itself leave that membership.

2. Fetch a snapshot

Once connected, request the first page:

from useceleris_client import CelerisError

try:
    page = await chat.presence_list(page=1, per_page=25)
except CelerisError as error:
    print("Presence query failed:", error.code, error)
else:
    print("Connections:", page.total)
    print("Page:", page.current_page)

    for connection in page.connections:
        print(connection.token_reference, connection.connection_id)

A query needs a connection and read permission, but no presence subscription.

from_ has a trailing underscore because from is a Python keyword.

3. Paginate and handle failures

Both arguments must be int: page from 1 to 2,147,483,647 and per_page from 1 to 100. Booleans, floats, strings and out-of-range values raise ConfigurationError; they are not converted or clamped.

from useceleris_client import PresenceConnection, Segment


async def list_connections(segment: Segment) -> list[PresenceConnection]:
    connections: list[PresenceConnection] = []
    page_number = 1

    while True:
        page = await segment.presence_list(page=page_number, per_page=25)
        connections.extend(page.connections)

        if not page.connections or page.to >= page.total:
            return connections

        page_number += 1


connections = await list_connections(chat)
print("Records fetched:", len(connections))

Only one query may be in flight per channel, even across segments: await one before starting another, or the second raises OperationInProgress.

A server refusal raises a ServerError from presence_list() at once, with sub_type "PRES_LIST", and does not also reach on_error. The default deadline is ten seconds; a timeout (Timeout) or cancelling the awaiting task frees the query slot without closing the connection, and a late reply is ignored. Queries are not retried; after a connection loss, query again once the channel recovers.

Past the last page, connections is empty and from_ > to; that is not an error.

Listings aggregate across the cluster, but pages are not an atomic snapshot: connections can join or leave between requests, so a multi-page result can omit or repeat records. Presence events are emitted only on the acting connection's server node, so events alone may miss connections on another node. Refresh listings when current state matters, and do not treat presence as a durable user roster.

4. Release presence resources

presence_subscription.cancel()
stop_presence()

Close the channel when its owner no longer needs it. The default segment has automatic message membership but still needs subscribe_presence() for presence events.

Next: Errors and troubleshooting.