Telegram Bot Bundle Laravel Package

Product Decisions This Supports

• Build vs. buy for the bot layer. v1.0.0 is the first stable release and ships the scaffolding most Telegram bots end up hand-rolling: an object-oriented Screen abstraction (supports() / handle()), a state-machine-friendly flow model, and a domain:action:args callback payload convention. That is roughly 2–4 engineer-weeks of architecture work you can skip if the shape fits.
• Scope sizing for conversational features. Because screens are isolated classes and state is delegated to your persistence layer, you can estimate onboarding wizards, KYC/forms, order tracking, or support triage as "one screen per step + one state column," which is a far more predictable estimate than a monolithic handler.
• Roadmap sequencing on chat surfaces. The package is Telegram-only. That makes it a good fit for a Telegram-first bet and a poor fit if the 12-month roadmap includes WhatsApp, Slack, or in-app chat — you would be building a channel-specific foundation and paying a re-architecture tax later.
• Ops model: webhook vs. long polling. Both transports are supported, so the decision can be made on infrastructure cost and compliance rather than on library capability. Webhooks favor stateless, autoscaled deployments; polling favors quick internal deployments and dev environments.
• Analytics and experimentation design. The standardized domain:action:args payload format is a free instrumentation contract — callback data becomes a structured event namespace you can log, funnel, and A/B against without inventing a taxonomy.
• Buy-in risk assessment. First release, non-standard license (CSSM-ULv2.0, not MIT/Apache), and a small vendor are procurement and continuity variables that belong in the decision record, not in a footnote.

When to Consider This Package

Consider it when:

• The product is Telegram-first and is expected to stay that way for at least two quarters.
• Your flows are genuinely multi-step (wizards, forms, approval chains) and you want an explicit screen/state model rather than a growing switch statement.
• You are on Symfony, or on a PHP stack willing to accept a Symfony bundle's service-container assumptions. Laravel shares many Symfony components, but bundle registration, autowiring semantics, and the HTTP kernel differ — treat this as an integration project, not a composer require.
• You want DI and testability by default — screens as autowired services are straightforward to unit test, which matters if bot logic will be covered by CI.
• You have an existing user/session store you want to keep; the package deliberately does not impose one.
• You are comfortable with async/ReactPHP-style runtimes or are willing to run polling as a supervised daemon.

Look elsewhere when:

• You need a Laravel-native developer experience. Nutgram, BotMan, and irazasyed/telegram-bot-sdk are the incumbent options and will cost your team less in integration friction, documentation, and hiring familiarity.
• Legal or procurement requires an OSI-approved license. CSSM-ULv2.0 ("Unlimited") must go through legal review before it touches production; if that review is slow or unfavorable, the evaluation is over.
• You need vendor support, an SLA, or a security disclosure process. A v1.0.0 from a single publisher is a bus-factor-1 dependency; plan to fork or wrap it.
• The roadmap is multi-channel. A Telegram-specific bundle becomes legacy the moment a second channel is committed.
• The bot is transactional and simple — one-way notifications, alerts, status pings. The architecture is over-engineered for that and a thin HTTP client is cheaper to own.
• You require long-term API stability guarantees; a first stable release has no track record of deprecation policy.

How to Pitch It (Stakeholders)

For executives: A first stable release of a Telegram bot framework that provides a structured, testable way to build multi-step conversational flows — the part of bot development that is usually custom and fragile. It is credible architecture, but it is young, from a small publisher, and carries a non-standard license. Recommendation: fund a two-week timeboxed spike against one real flow, with legal review of the license running in parallel, before committing it to the platform roadmap. Do not standardize on it yet.

For engineering: The Screen + payload-routing model is a clean separation of concerns and should be more testable than handler-based bots. Two caveats to price in: (1) it is a Symfony bundle, so adopting it in a Laravel codebase means bridging service registration and container semantics — budget for that explicitly or prototype on Symfony first; (2) long polling needs a supervised worker, and the async story assumes ReactPHP rather than Laravel's queue/Octane model, so confirm the runtime shape before designing around it. State persistence is intentionally left to us — that is flexibility, not a gap, but it is design work we own.

For legal and procurement: Verify the CSSM-ULv2.0 terms against our redistribution, sublicensing, and attribution obligations, and confirm whether the "Unlimited" grant survives our intended deployment model. Flag the single-maintainer risk and record a fallback plan (fork or thin wrapper) in the dependency register.