chattolib

Unofficial async Python client library for the Chatto webchat API.

Chattolib versions track the Chatto server version they target. The current release targets Chatto's ConnectRPC API. Request/response traffic uses the official connectrpc Python package; the realtime channel is a binary protobuf WebSocket at /api/realtime (needs the [realtime] extra).

Install

pip install chattolib

Quick start

import asyncio
from chattolib import ChattoClient

async def main():
    # Public discovery — no auth required
    async with ChattoClient() as anon:
        profile, login = await anon.get_server()
        print(f"Chatto {profile.version}: {profile.name}")

    # Authenticated calls
    async with await ChattoClient.login("username", "password") as client:
        me = await client.me()
        print(f"Logged in as {me.display_name}")

        for entry in await client.list_rooms():
            if entry.room:
                print(f"  - {entry.room.name}")

asyncio.run(main())

Realtime

Install with the extra:

pip install 'chattolib[realtime]'

Then stream live events:

from chattolib import stream_events

async with await ChattoClient.login("username", "password") as client:
    async for event in stream_events(client):
        print(event.kind, event.actor_id, event.payload)

event.kind names the protobuf oneof case (message_posted, reaction_added, presence_changed, notification_created, …). event.payload is the concrete protobuf sub-message — access its fields directly (e.g. event.payload.room_id). Realtime events are invalidation signals; use the corresponding Connect RPC (GetRoomEventsAround, GetNotification, GetUser, …) to hydrate the referenced resource.

Escape hatch

ChattoClient.services exposes the underlying connectrpc service clients directly (one per Chatto service), for anything the Pythonic wrappers don't yet cover. For example:

from chattolib._pb.chatto.api.v1 import messages_pb2

resp = await client.services.messages.get_message(
    messages_pb2.GetMessageRequest(room_id=..., event_id=...)
)

License

• chattolib's own code is licensed under MPL-2.0 (Mozilla Public License 2.0) — a weak, file-level copyleft. You can use, distribute, and embed chattolib in commercial or proprietary software; modifications to the library's own files must be released under MPL-2.0.
• Vendored Chatto protobuf definitions under proto/chatto/** and the generated bindings under src/chattolib/_pb/chatto/** are Apache-2.0, matching upstream chattocorp/chatto.
• Vendored buf.validate material is Apache-2.0 (from bufbuild/protovalidate).

See LICENSING.md for the full picture and REUSE.toml for the machine-readable licence map.

Note: chattolib versions 0.0.1 through 0.4.9 were released under MIT. Those releases remain MIT-licensed forever on PyPI; the MPL-2.0 relicence applies to newly published releases only.