Live watching — TeleGlance

watch

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

TypeScript

import { watch } from 'teleglance';

for await (const message of watch(client, 'telegram', 30000)) {
  console.log(`New message: ${message.id}`);
  console.log(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.

TypeScript

import { watch, JsonCheckpointStore, CheckpointState } from 'teleglance';

const store = new JsonCheckpointStore('watch.json');
let state = await store.load('watch:telegram');

// Start watching from last seen message
const sinceId = state?.newestId;

for await (const message of watch(client, 'telegram', 30000, sinceId)) {
  console.log(`New: ${message.id}`);

  // Update checkpoint
  if (!state) {
    state = new CheckpointState('telegram', message.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.

TypeScript

import { watch } from 'teleglance';
import { ChannelNotFound, ChannelPrivate } from 'teleglance';

try {
  for await (const message of watch(client, 'telegram', 30000)) {
    process(message);
  }
} catch (err) {
  if (err instanceof ChannelNotFound) {
    console.error('Channel was deleted');
  } else if (err instanceof ChannelPrivate) {
    console.error('Channel was made private');
  } else {
    throw err;
  }
}

Interval tuning

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

TypeScript

// High-frequency channel (post every few minutes)
for await (const msg of watch(client, 'breaking_news', 10000)) {
  alert(msg);
}

// Low-frequency channel (few posts per day)
for await (const msg of watch(client, 'announcements', 300000)) {
  archive(msg);
}

// Minimum safe interval is ~5000ms (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 30000

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

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