Getting Started

First, the framing: this is a Symfony bundle, not a Laravel package. Laravel has no bundle kernel, so composer require m4n50n/telegram-bot-bundle will not register routes, services, or Artisan commands for you. There are two realistic ways a Laravel developer touches this repo:

You are actually running Symfony (e.g., a bot microservice) and Laravel is the API/back office. Use the bundle as intended there.
You are in Laravel and want the wrapper's ideas, not the wrapper itself. In that case require the underlying library (longman/telegram-bot) directly and copy the bundle's DI wiring into a service provider.

Minimal path for case 1:

composer require m4n50n/telegram-bot-bundle

Then in config/bundles.php:

M4n50n\TelegramBotBundle\TelegramBotBundle::class => ['all' => true],

Configure the bot token via env (TELEGRAM_BOT_TOKEN) in config/packages/telegram_bot.yaml, then use the polling entry point that ships with the bundle to prove connectivity with a plain /start echo.

Minimal path for case 2 (Laravel):

composer require longman/telegram-bot

Create config/telegram.php with token, username, webhook_secret, register a singleton binding for Longman\TelegramBot\Telegram in AppServiceProvider, and add a single POST /telegram/webhook route. That is the "hello world" — one update in, one sendMessage out.

Where to look first in this repo:

src/DependencyInjection/Configuration.php and ...Extension.php — this is the canonical list of what the bundle makes configurable (token, commands paths, limits, logging). Treat it as your spec when re-implementing in Laravel.
src/Resources/config/services.* — shows how Telegram is wired, which is exactly the constructor wiring you need for a Laravel singleton.
The bundled console command(s) — the polling/setWebhook commands are the fastest way to understand lifecycle and what long-running behavior expects.

Your first real use case should be a webhook receiver that acknowledges fast and dispatches a job, not polling. Polling is fine for a spike, but it fights PHP-FPM and queue workers.

Implementation Patterns

Pattern A: Symfony bot service, Laravel orchestrates

Keep the bundle in a small Symfony app (or a single-process CLI worker). Laravel talks to it over HTTP or a shared queue (Redis/SQS). This is the least surprising use of the package and isolates its low maintenance risk (18 stars, 0 dependents, last release Feb 2024) to one deployable.

Laravel emits domain events → queue → Symfony bot worker consumes → calls Telegram.
Bot worker posts inbound updates to a Laravel webhook (/api/telegram/inbound) so your Laravel app owns user state, auth, and business logic.

Pattern B: Port the wiring into Laravel

Mirror the bundle's config surface so behavior stays familiar if you ever migrate:

// AppServiceProvider::register()
$this->app->singleton(Telegram::class, function ($app) {
    $config = $app['config']['telegram'];
    $telegram = new Telegram($config['token'], $config['username']);
    $telegram->addCommandsPaths($config['commands_paths']);
    $telegram->enableLimiter(); // if you want the built-in per-chat limiter
    return $telegram;
});

Then a controller that only does routing + dispatch:

public function __invoke(Request $request, Telegram $telegram)
{
    $update = Update::createFromJson($request->getContent());
    ProcessTelegramUpdate::dispatch($update->toJson());
    return response()->noContent();
}

And a queued job that owns the actual command handling (/start, /help, callback queries). Use the library's Command classes, CommandBus, and Conversation primitives — or your own match statement if the bot is small. The bundle's value here is as a reference implementation; longman/telegram-bot is the substance.

Workflow tips that apply either way

Route by update type, not text. Separate handling for message, callback_query, edited_message, and channel_post. Inline keyboard callbacks are the most common source of "why did my handler not fire" bugs.
Conversation state belongs in a real store. The library's Conversation needs a persistent driver; in Laravel back it with cache or a telegram_conversations table keyed by chat_id.
Idempotency by update_id. Telegram retries. Store processed update_ids (cache with TTL is fine) and short-circuit duplicates before doing anything with side effects.
Return 200 in < 1s. Telegram's webhook timeout is short; anything slow means retries and duplicate work. Everything real goes behind dispatch().
Commands as classes, one per file, registered via a commands path — this matches both the bundle and longman conventions and keeps the router trivial as the bot grows.
Testing: build fixtures from raw Telegram JSON and feed them through Update::createFromJson(). This exercises your real parsing path without hitting the API. Mock the Request layer for outbound assertions.

Gotchas and Tips

The bundle will not auto-discover in Laravel. No extra.laravel.providers, no vendor:publish, no config merge. Every "install" step in the README assumes config/bundles.php. Budget an hour to translate DI tags into Laravel container bindings — the tags are the part people miss.
Pin longman/telegram-bot explicitly. The library had breaking API changes across majors, and this bundle's constraint is a snapshot from Feb 2024. If Composer resolves a newer major, expect Request/Response signature drift.
setWebhook and polling are mutually exclusive. Running the polling command while a webhook is set silently produces no updates (or doubles). deleteWebhook before polling; getWebhookInfo is your first debugging call when updates stop arriving.
Telegram returns HTTP 200 with "ok": false. Naive $response->successful() checks pass while the bot is broken. Always inspect the JSON ok/error_code/description, and log them — the library surfaces these but only if you look.
Secrets and webhook hardening. Token in env only; set secret_token on setWebhook and validate the X-Telegram-Bot-Api-Secret-Token header in your controller. HTTPS with a valid cert is non-negotiable.
Rate limits are real. ~30 messages/second globally, ~1/second per chat. The library's limiter helps outbound, but bursty fan-out from a Laravel job batch will still get you 429 with retry_after. Respect it; don't retry immediately.
Long-running processes and PHP-FPM. max_execution_time, memory limits, and the lack of a supervisor are the usual killers. If you poll, do it in a php artisan worker under supervisor/systemd, not a request.
File handling needs two calls. getFile then download from https://api.telegram.org/file/bot<token>/<file_path>. Check file_size against the 20MB bot download limit before trying.
Extension points (if you're inside Symfony): the bundle's service tags for commands and its config for command paths; in Laravel the equivalents are your container tags and a telegram.commands config array. Custom SystemCommands are the cleanest hook for /start-style bootstrapping.
Maintenance risk is the headline. 18 stars, zero dependents, no release since Feb 2024, and a transitive dependency on a fast-moving library. If you go with it, vendor the config wiring or fork it. Do not build a business-critical bot on the assumption that a Symfony 7.2 / longman v4 incompatibility will be fixed upstream promptly.
Version compatibility check before you commit: verify the bundle's symfony/* constraints against your Symfony version and its longman/telegram-bot constraint against the API you intend to write against. This is the single most likely blocker you'll hit on day one.

Telegram Bot Bundle Laravel Package