Live watching — TeleGlance

watch

Poll a channel for new messages in real-time. The watcher handles transient failures automatically and only propagates fatal errors.

Python

async for message in client.watch("telegram", interval=30.0):
    print(f"New message: {message.id}")
    print(message.text)

# The loop runs forever until interrupted or the channel becomes inaccessible

Resume from checkpoint

Combine watch with checkpoints to avoid missing messages across restarts.

Python

from teleglance import JsonCheckpointStore

store = JsonCheckpointStore("watch.json")
state = await store.load("watch:telegram")

# Start watching from last seen message
since_id = state.newest_id if state else None

async for message in client.watch("telegram", interval=30.0, since_id=since_id):
    print(f"New: {message.id}")

    # Update checkpoint
    if state is None:
        from teleglance import CheckpointState
        state = CheckpointState(channel="telegram", oldest_id=message.id, newest_id=message.id)
    else:
        state = state.record(message)

    await store.save("watch:telegram", state)

Error handling

Transient errors (rate limits, network issues, parse failures) are logged and retried automatically. Fatal errors (channel deleted, made private) propagate immediately.

Python

import logging
from teleglance import ChannelNotFound, ChannelPrivate

logging.basicConfig(level=logging.WARNING)

try:
    async for message in client.watch("telegram", interval=30.0):
        process(message)
except ChannelNotFound:
    print("Channel was deleted")
except ChannelPrivate:
    print("Channel was made private")
except KeyboardInterrupt:
    print("Stopped by user")

Interval tuning

Choose an interval based on channel activity and rate-limit tolerance.

Python

# High-frequency channel (post every few minutes)
async for msg in client.watch("breaking_news", interval=10.0):
    alert(msg)

# Low-frequency channel (few posts per day)
async for msg in client.watch("announcements", interval=300.0):
    archive(msg)

# Minimum safe interval is ~5 seconds to avoid rate limiting

CLI watch

The CLI can watch channels and append to NDJSON files.

Bash

# Watch and print to stdout
teleglance watch telegram --interval 30

# Append to NDJSON file
teleglance watch telegram --interval 30 --output watch.ndjson

# Resume from existing NDJSON (reads last line)
teleglance watch telegram --interval 30 --output watch.ndjson --resume