Televerse Documentation

Televerse supports the two distinct methods provided by Telegram for receiving updates: Long Polling and Webhooks. Understanding the difference between them is key to building an efficient bot.

Long Polling

Your bot actively requests updates from Telegram. Best for development and simple bots.

No public IP/domain required
Easiest to set up
Works behind firewalls

Webhooks

Telegram sends updates to your server. Best for production and high-traffic bots.

Lower latency
Less resource intensive
Requires HTTPS & public URL

Long Polling

Long Polling is the default behavior in Televerse. When you call bot.start() without arguments, it automatically sets up a LongPollingFetcher.

main.dart

import 'package:televerse/televerse.dart';

void main() async {
  final bot = Bot('YOUR_BOT_TOKEN');

  // Start with default Long Polling
  await bot.start();
}

Advanced Configuration

You can customize the polling behavior using LongPollingConfig. Televerse provides presets for common use cases.

main.dart

// Low latency configuration (faster updates, more requests)
final lowLatency = LongPollingConfig.lowLatency();

// High throughput configuration (more efficient for many updates)
final highThroughput = LongPollingConfig.highThroughput();

// Custom configuration
final customConfig = LongPollingConfig(
  timeout: 40,
  limit: 50,
  allowedUpdates: [UpdateType.message, UpdateType.callbackQuery],
);

await bot.start(LongPollingFetcher(
  bot.api,
  config: customConfig,
));

Webhooks

For production bots, Webhooks are often preferred as they are more efficient. Televerse comes with a built-in highly performant HTTP server making webhook setup trivial.

Easiest Way: startWebhook

The startWebhook method handles everything for you: starting the server, setting the webhook with Telegram, and listening for updates.

main.dart

void main() async {
  final bot = Bot('YOUR_BOT_TOKEN');

  // Start a webhook server on port 8080
  await bot.startWebhook(
    webhookUrl: 'https://your-domain.com/webhook',
    port: 8080,
  );
}

This automatically monitors the /webhook path on the specified port.

Local Development with Ngrok

During development, you might want to test webhooks using a tunneling service like ngrok. The startWebhookDev helper is designed exactly for this.

main.dart

void main() async {
  final bot = Bot('YOUR_BOT_TOKEN');

  // Automatically configures for local development
  // 1. Sets up server on port 8080
  // 2. Uses the provided ngrok URL
  // 3. Drops pending updates
  await bot.startWebhookDev('https://your-ngrok-url.ngrok-free.app');
}

Production Configuration

For full control over the webhook configuration (custom paths, secret tokens, max connections), use the WebhookConfig and pass it to a WebhookFetcher.

main.dart

// Production-ready webhook configuration
final config = WebhookConfig.production(
  webhookUrl: 'https://your-domain.com/webhook',
  port: 8443,
  secretToken: 'your-secure-secret-token',
  maxConnections: 60,
  allowedUpdates: [UpdateType.message, UpdateType.editedMessage],
);

final fetcher = WebhookFetcher(
  api: bot.api, 
  config: config,
);

await bot.start(fetcher);

Security Note: In production, always use a secretToken to verify that incoming requests are actually from Telegram.

Which one to choose?

Start with Long Polling for development. It's hassle-free and requires no server configuration.

Switch to Webhooks when you deploy your bot to a server or if your bot has high traffic. Webhooks are more resource-efficient as your bot doesn't need to constantly ask "Are there new messages?".