# tueen/telegram
> The Royal Telegram Bot SDK for Modern PHP (PHP 8.4+)

Package Name: tueen/telegram
GitHub Repository: https://github.com/tueen/telegram/
Base URL: https://tueen.github.io/telegram/
Documentation Root: https://tueen.github.io/telegram/guide/
Coverage: Complete Telegram Bot API (all methods, types, and property enums)
Bot API Constant: Telegram::BOT_API_VERSION

> Note: All documentation links below are relative to `Base URL`. If the documentation or guides are not sufficient for your task, inspect the source code, tests, and examples directly on GitHub: https://github.com/tueen/telegram/

## AI Agent Skill & Coding Guidelines
When writing code for `tueen/telegram`, AI assistants and agents MUST adhere to these architectural rules:
1. Always enable strict types: `declare(strict_types=1);`.
2. Property access & visibility: Use asymmetric visibility `private(set)` (never `public private(set)`).
3. Property hooks: Prefer property hooks over repetitive getter/setter methods.
4. Universal ok(): All response types inherit from base `Type` and supply `ok(): bool` and `isOk(): bool`.
5. Error Handling: Default mode throws typed exceptions; or use `withErrorObjectMode()` to receive typed `Error` objects.
6. Forward compatibility: Unknown future Telegram fields are dynamically accessed or retrieved via `$extra`.
7. Pipeline pattern: Callables and middlewares support the Pipe Operator (`|>`) and fluent config builder.
8. Repository Inspection Fallback: If documentation is insufficient or missing edge-case details, check the GitHub repository at https://github.com/tueen/telegram/ for full source code, types, and test suites.

## Complete Documentation Map & Topic Outline

### Getting Started
- [Getting Started](/guide/getting-started): > The Royal Telegram Bot SDK for Modern PHP
  - [Introduction](/guide/getting-started#introduction)
  - [Requirements](/guide/getting-started#requirements)
  - [Installation](/guide/getting-started#installation)
  - [Client Initialization](/guide/getting-started#client-initialization)
    * [Direct Initialization](/guide/getting-started#direct-initialization)
    * [Fluent ConfigBuilder](/guide/getting-started#fluent-configbuilder)
  - [Supported Bot API Version](/guide/getting-started#supported-bot-api-version)
  - [First API Call: `getMe`](/guide/getting-started#first-api-call-getme)
  - [Sending a Message](/guide/getting-started#sending-a-message)
  - [Handling Incoming Updates](/guide/getting-started#handling-incoming-updates)
  - [Next Steps](/guide/getting-started#next-steps)
- [The Telegram Client](/guide/telegram-client): The Tueen\Telegram\Telegram class (conventionally instantiated as $bot) is the primary entry point and client facade of the tueen/telegram library. It provides a unified, strictly typed interface for sending Bot API requests, listening for updates, managing multi-step flows, and resolving contextual parameters.
  - [🚀 1. Instantiation](/guide/telegram-client#1-instantiation)
    * [Basic Instantiation](/guide/telegram-client#basic-instantiation)
    * [Advanced Instantiation with `ConfigBuilder`](/guide/telegram-client#advanced-instantiation-with-configbuilder)
  - [⚡ 2. The Three Primary Roles of `$bot`](/guide/telegram-client#2-the-three-primary-roles-of-bot)
    * [1. Direct Bot API Client](/guide/telegram-client#1-direct-bot-api-client)
    * [2. Update Router & Dispatcher](/guide/telegram-client#2-update-router-dispatcher)
    * [3. Contextual Entity Resolver (PHP 8.4 Property Hooks)](/guide/telegram-client#3-contextual-entity-resolver-php-84-property-hooks)
  - [💡 3. Client Best Practices](/guide/telegram-client#3-client-best-practices)
    * [1. Always Use PHP Named Arguments](/guide/telegram-client#1-always-use-php-named-arguments)
    * [2. Reusing a Single Client Instance](/guide/telegram-client#2-reusing-a-single-client-instance)
    * [3. Organizing Complex Bots with Controllers](/guide/telegram-client#3-organizing-complex-bots-with-controllers)
  - [🏛️ 4. Architecture & Decoupled Subsystems](/guide/telegram-client#4-architecture-decoupled-subsystems)
    * [When to Access Subsystems Directly:](/guide/telegram-client#when-to-access-subsystems-directly)
  - [🧭 5. Complete Method & Property Reference](/guide/telegram-client#5-complete-method-property-reference)
    * [🏛️ Class Constants & Public Properties](/guide/telegram-client#class-constants-public-properties)
    * [A. Initialization & Testing Factory](/guide/telegram-client#a-initialization-testing-factory)
    * [B. Execution & Running Modes](/guide/telegram-client#b-execution-running-modes)
    * [C. Update Pipeline & Middleware](/guide/telegram-client#c-update-pipeline-middleware)
    * [D. Exception & Error Handling](/guide/telegram-client#d-exception-error-handling)
    * [E. Update Routing & Controllers](/guide/telegram-client#e-update-routing-controllers)
    * [F. Multi-Step Conversational Flows](/guide/telegram-client#f-multi-step-conversational-flows)
    * [G. Contextual Accessors & Property Hooks](/guide/telegram-client#g-contextual-accessors-property-hooks)
    * [H. Bot API Method Calls & File Operations](/guide/telegram-client#h-bot-api-method-calls-file-operations)
    * [I. Underlying Subsystems & Dependency Injection](/guide/telegram-client#i-underlying-subsystems-dependency-injection)
- [Configuration](/guide/configuration): tueen/telegram features an immutable configuration architecture paired with an expressive, fluent ConfigBuilder. Every parameter — from networking timeouts and persistent connection pooling to progress event hooks, running modes, and error handling strategies — is strictly typed and discoverable via IDE autocompletion.
  - [🛠️ 1. Creating Configuration](/guide/configuration#1-creating-configuration)
    * [Fluent Builder via `Telegram::create()`](/guide/configuration#fluent-builder-via-telegramcreate)
    * [Direct Instantiation of `Config`](/guide/configuration#direct-instantiation-of-config)
  - [🧭 2. Detailed Configuration Reference](/guide/configuration#2-detailed-configuration-reference)
    * [🌐 Server & Credentials](/guide/configuration#server-credentials)
    * [⚡ HTTP Client, Networking & Transport](/guide/configuration#http-client-networking-transport)
    * [📊 Progress Tracking Callbacks](/guide/configuration#progress-tracking-callbacks)
    * [🛡️ Error Handling Strategy](/guide/configuration#error-handling-strategy)
    * [🚀 Running Modes & Resiliency](/guide/configuration#running-modes-resiliency)
    * [🔄 Conversation Flow & Orchestration](/guide/configuration#conversation-flow-orchestration)
    * [📋 Logging & Observability](/guide/configuration#logging-observability)
    * [💉 Dependency Injection & Container](/guide/configuration#dependency-injection-container)
    * [⚡ Client Instantiation Shortcuts](/guide/configuration#client-instantiation-shortcuts)
  - [🧬 3. Immutability & Modern PHP 8.5 Patterns](/guide/configuration#3-immutability-modern-php-85-patterns)
  - [🌐 4. Standard URI & URL Resolution Properties](/guide/configuration#4-standard-uri-url-resolution-properties)
  - [💡 5. Real-World Configuration Recipes](/guide/configuration#5-real-world-configuration-recipes)
    * [Recipe 1: Production Webhook with Persistent cURL & Monolog](/guide/configuration#recipe-1-production-webhook-with-persistent-curl-monolog)
    * [Recipe 2: High-Volume CLI Long-Polling Worker](/guide/configuration#recipe-2-high-volume-cli-long-polling-worker)
    * [Recipe 3: Tor / SOCKS5 Proxy for Restricted Environments](/guide/configuration#recipe-3-tor-socks5-proxy-for-restricted-environments)
    * [Recipe 4: Self-Hosted Local Bot API Server (2GB Uploads)](/guide/configuration#recipe-4-self-hosted-local-bot-api-server-2gb-uploads)
    * [Recipe 5: Laravel & Symfony PSR-11 Container Integration](/guide/configuration#recipe-5-laravel-symfony-psr-11-container-integration)
    * [Recipe 6: Adaptive AutoMode Execution (Unified CLI & HTTP Webhook)](/guide/configuration#recipe-6-adaptive-automode-execution-unified-cli-http-webhook)

### Core Essentials
- [Calling Methods & Types](/guide/methods-and-types): tueen/telegram provides native, strictly typed support for Telegram Bot API methods and types with full IDE autocompletion, enums, computed property hooks, and forward-compatible fallbacks.
  - [🚀 1. Method Invocations](/guide/methods-and-types#1-method-invocations)
    * [Dynamic Method Calls (Recommended)](/guide/methods-and-types#dynamic-method-calls-recommended)
    * [Method Objects (For Custom Pipelines & Architecture)](/guide/methods-and-types#method-objects-for-custom-pipelines-architecture)
    * [Forward-Compatible Unknown / New Parameters](/guide/methods-and-types#forward-compatible-unknown-new-parameters)
    * [Passing Complex & Nested Types (Objects or Arrays)](/guide/methods-and-types#passing-complex-nested-types-objects-or-arrays)
  - [🏛️ 2. The Universal Base `Type` Class](/guide/methods-and-types#2-the-universal-base-type-class)
    * [Core Features of `Type`:](/guide/methods-and-types#core-features-of-type)
  - [⚙️ 3. The Base `Method` Class](/guide/methods-and-types#3-the-base-method-class)
    * [Core Responsibilities of `Method`:](/guide/methods-and-types#core-responsibilities-of-method)
  - [🧩 4. Concerns & Computed Helpers](/guide/methods-and-types#4-concerns-computed-helpers)
  - [📦 5. Custom Result Wrapper Types](/guide/methods-and-types#5-custom-result-wrapper-types)
  - [🧭 6. Methods & Types API Reference](/guide/methods-and-types#6-methods-types-api-reference)
    * [🏛️ Base `Type` Class (`Tueen\Telegram\Types\Type`)](/guide/methods-and-types#base-type-class-tueentelegramtypestype)
    * [⚙️ Base `Method` Class (`Tueen\Telegram\Methods\Method`)](/guide/methods-and-types#base-method-class-tueentelegrammethodsmethod)
    * [🎯 Contextual Parameter Auto-Injection](/guide/methods-and-types#contextual-parameter-auto-injection)
    * [📦 Custom Wrapper Types (`Tueen\Telegram\Types\Custom\`)](/guide/methods-and-types#custom-wrapper-types-tueentelegramtypescustom)
- [Fluent Keyboard Builders](/guide/keyboards): tueen/telegram provides modern, fluent builders for creating both Inline Keyboards (InlineKeyboardMarkup) and Reply Keyboards (ReplyKeyboardMarkup / ReplyKeyboardRemove).
  - [🔘 1. Inline Keyboards (`InlineKeyboard`)](/guide/keyboards#1-inline-keyboards-inlinekeyboard)
    * [Basic Usage](/guide/keyboards#basic-usage)
    * [Supported Button Types](/guide/keyboards#supported-button-types)
    * [Auto-Chunking Buttons (`chunk`)](/guide/keyboards#auto-chunking-buttons-chunk)
  - [⌨️ 2. Reply Keyboards (`ReplyKeyboard`)](/guide/keyboards#2-reply-keyboards-replykeyboard)
    * [Basic Usage](/guide/keyboards#basic-usage)
    * [Supported Features & Button Types](/guide/keyboards#supported-features-button-types)
    * [Dismissing Keyboards (`ReplyKeyboard::remove`)](/guide/keyboards#dismissing-keyboards-replykeyboardremove)
  - [🧭 3. Keyboard Builders API Reference](/guide/keyboards#3-keyboard-builders-api-reference)
    * [🔘 `InlineKeyboard` Builder (`Tueen\Telegram\Keyboards\InlineKeyboard`)](/guide/keyboards#inlinekeyboard-builder-tueentelegramkeyboardsinlinekeyboard)
    * [⌨️ `ReplyKeyboard` Builder (`Tueen\Telegram\Keyboards\ReplyKeyboard`)](/guide/keyboards#replykeyboard-builder-tueentelegramkeyboardsreplykeyboard)
- [Text Formatting & Escaping](/guide/formatting): Telegram supports rich text formatting via HTML, MarkdownV2, and legacy Markdown. However, unescaped characters (such as , , [, <, >, &) frequently cause Telegram API errors like 400 Bad Request: can't parse entities.
  - [🎨 1. Fluent `Text` Builder](/guide/formatting#1-fluent-text-builder)
    * [Direct API Integration](/guide/formatting#direct-api-integration)
    * [HTML Formatting (`Text::html`)](/guide/formatting#html-formatting-texthtml)
    * [MarkdownV2 Formatting (`Text::markdownV2`)](/guide/formatting#markdownv2-formatting-textmarkdownv2)
  - [🔗 2. Nested Formatting Styles](/guide/formatting#2-nested-formatting-styles)
  - [🛡️ 3. Low-Level Escaping with `Escape`](/guide/formatting#3-low-level-escaping-with-escape)
  - [🧭 4. Formatting API Catalog](/guide/formatting#4-formatting-api-catalog)
    * [🎨 `Text` Builder (`Tueen\Telegram\Formatting\Text`)](/guide/formatting#text-builder-tueentelegramformattingtext)
    * [🛡️ `Escape` Helper (`Tueen\Telegram\Formatting\Escape`)](/guide/formatting#escape-helper-tueentelegramformattingescape)
- [File Upload & Download](/guide/file-upload-download): tueen/telegram makes file transfers seamless using the InputFile wrapper, streaming HTTP transports, and real-time upload/download progress callbacks.
  - [📤 1. File Uploads with `InputFile`](/guide/file-upload-download#1-file-uploads-with-inputfile)
    * [From Local File Path](/guide/file-upload-download#from-local-file-path)
    * [From Stream Resource](/guide/file-upload-download#from-stream-resource)
    * [From Raw In-Memory String](/guide/file-upload-download#from-raw-in-memory-string)
  - [🖼️ 2. Sending Media Groups (Albums)](/guide/file-upload-download#2-sending-media-groups-albums)
  - [⚡ 3. Real-Time Upload Progress](/guide/file-upload-download#3-real-time-upload-progress)
  - [📥 4. Streaming File Downloads with Progress](/guide/file-upload-download#4-streaming-file-downloads-with-progress)
  - [🧭 5. File Transfer API Catalog](/guide/file-upload-download#5-file-transfer-api-catalog)
    * [📦 `InputFile` Wrapper (`Tueen\Telegram\Types\Custom\InputFile`)](/guide/file-upload-download#inputfile-wrapper-tueentelegramtypescustominputfile)
    * [📥 Client Download APIs (`Telegram`)](/guide/file-upload-download#client-download-apis-telegram)

### Updates & Routing
- [Running Modes](/guide/running-modes): tueen/telegram features an elegant execution strategy separating how updates are received from how they are processed.
  - [🚀 Unified Execution with `$bot->run()`](/guide/running-modes#unified-execution-with-bot-run)
    * [1. Handler Signature](/guide/running-modes#1-handler-signature)
    * [2. Invokable Handler Classes](/guide/running-modes#2-invokable-handler-classes)
    * [3. Multiple Handlers & Middleware Chains](/guide/running-modes#3-multiple-handlers-middleware-chains)
  - [📦 The `$bot->update` Property](/guide/running-modes#the-bot-update-property)
  - [1. Webhook Mode (`WebhookMode`)](/guide/running-modes#1-webhook-mode-webhookmode)
    * [Basic Setup](/guide/running-modes#basic-setup)
    * [Secret Token Verification](/guide/running-modes#secret-token-verification)
    * [Fast Response (`safeResponse`)](/guide/running-modes#fast-response-saferesponse)
    * [Integration with Frameworks (Laravel, Symfony, PSR-7)](/guide/running-modes#integration-with-frameworks-laravel-symfony-psr-7)
  - [2. Long-Polling Mode (`PollingMode`)](/guide/running-modes#2-long-polling-mode-pollingmode)
    * [Continuous Listening](/guide/running-modes#continuous-listening)
    * [Multi-Process Concurrency (`forkProcess`)](/guide/running-modes#multi-process-concurrency-forkprocess)
    * [Custom Process Dispatcher](/guide/running-modes#custom-process-dispatcher)
    * [Features of `PollingMode`:](/guide/running-modes#features-of-pollingmode)
    * [Manual Generator Iteration](/guide/running-modes#manual-generator-iteration)
  - [Native Telegram Bot API Method: `getUpdates`](/guide/running-modes#native-telegram-bot-api-method-getupdates)
  - [Setting Running Mode via Config](/guide/running-modes#setting-running-mode-via-config)
  - [⚡ AutoMode: Adaptive Execution (CLI Polling & HTTP Webhook)](/guide/running-modes#automode-adaptive-execution-cli-polling-http-webhook)
    * [Key Features of `AutoMode`:](/guide/running-modes#key-features-of-automode)
    * [Example 1: Fluent Builder Configuration](/guide/running-modes#example-1-fluent-builder-configuration)
    * [Example 2: Quick `$bot->autoRun()` Execution](/guide/running-modes#example-2-quick-bot-autorun-execution)
  - [🔀 PHP 8.5 Pipe Operator (`|>`) Pipelines](/guide/running-modes#php-85-pipe-operator-pipelines)
    * [1. Fundamental Syntax & First-Class Callables](/guide/running-modes#1-fundamental-syntax-first-class-callables)
    * [2. Production Webhook Ingestion Pipeline](/guide/running-modes#2-production-webhook-ingestion-pipeline)
    * [3. Multi-Stage Filter & Guard Pipeline](/guide/running-modes#3-multi-stage-filter-guard-pipeline)
    * [4. Direct Action & Response Pipelines](/guide/running-modes#4-direct-action-response-pipelines)
    * [5. Architectural Benefits in Tueen](/guide/running-modes#5-architectural-benefits-in-tueen)
  - [🧭 6. Running Modes API Catalog](/guide/running-modes#6-running-modes-api-catalog)
    * [🌐 `WebhookMode` Runner (`Tueen\Telegram\Running\WebhookMode`)](/guide/running-modes#webhookmode-runner-tueentelegramrunningwebhookmode)
    * [🔄 `PollingMode` Runner (`Tueen\Telegram\Running\PollingMode`)](/guide/running-modes#pollingmode-runner-tueentelegramrunningpollingmode)
    * [🔀 `AutoMode` Runner (`Tueen\Telegram\Running\AutoMode`)](/guide/running-modes#automode-runner-tueentelegramrunningautomode)
- [Update Routing & Attributes](/guide/routing): Instead of writing monolithic switch or if/else ladders inside your update handlers, tueen/telegram features an expressive, type-safe Update Router.
  - [⚡ 1. Fluent Routing](/guide/routing#1-fluent-routing)
  - [🎯 2. Parameter Extraction in Routes](/guide/routing#2-parameter-extraction-in-routes)
  - [🏛️ 3. Attribute-Driven Controllers](/guide/routing#3-attribute-driven-controllers)
    * [Example Controller](/guide/routing#example-controller)
    * [Registering Controllers](/guide/routing#registering-controllers)
  - [🧭 4. Routing API Catalog](/guide/routing#4-routing-api-catalog)
    * [🏷️ Routing Attributes (`Tueen\Telegram\Routing\Attributes\`)](/guide/routing#routing-attributes-tueentelegramroutingattributes)
  - [🚨 4. Priority Routes (Overriding Active Flows)](/guide/routing#4-priority-routes-overriding-active-flows)
    * [Registering Priority Routes](/guide/routing#registering-priority-routes)
    * [Flow Customization & Interception](/guide/routing#flow-customization-interception)
    * [🛣️ `Router` Methods (`Tueen\Telegram\Routing\Router`)](/guide/routing#router-methods-tueentelegramroutingrouter)
- [Update & Message Helpers](/guide/update-and-message-helpers): tueen/telegram provides helper methods and computed properties on Update, Message, Chat, and User objects to simplify event processing and eliminate boilerplate null checks.
  - [⚡ 1. Update Helpers (`Update`)](/guide/update-and-message-helpers#1-update-helpers-update)
    * [Checking Update Types (`isType`)](/guide/update-and-message-helpers#checking-update-types-istype)
    * [Smart In-Memory Model Finders](/guide/update-and-message-helpers#smart-in-memory-model-finders)
    * [ID & File Shortcut Finders](/guide/update-and-message-helpers#id-file-shortcut-finders)
    * [Modern PHP 8.4 Property Hooks](/guide/update-and-message-helpers#modern-php-84-property-hooks)
  - [🌐 2. Client-Level Contextual Shortcuts (`Telegram` & `Context`)](/guide/update-and-message-helpers#2-client-level-contextual-shortcuts-telegram-context)
  - [💬 3. Message Helpers (`Message`)](/guide/update-and-message-helpers#3-message-helpers-message)
    * [Checking Message Types (`isType` & `isMessage`)](/guide/update-and-message-helpers#checking-message-types-istype-ismessage)
    * [Checking Replies (`isRepliedToMessage`)](/guide/update-and-message-helpers#checking-replies-isrepliedtomessage)
    * [Extracting Any Text, Caption, or Rich Text (`findAnyText`)](/guide/update-and-message-helpers#extracting-any-text-caption-or-rich-text-findanytext)
    * [Media & File ID Extraction (`findFileId` & `findLargestPhoto`)](/guide/update-and-message-helpers#media-file-id-extraction-findfileid-findlargestphoto)
    * [Bot Command Parsing](/guide/update-and-message-helpers#bot-command-parsing)
  - [👤 4. Chat & User Helpers](/guide/update-and-message-helpers#4-chat-user-helpers)
    * [Automatic `fullName`](/guide/update-and-message-helpers#automatic-fullname)
  - [🧭 5. Complete Helpers API Catalog](/guide/update-and-message-helpers#5-complete-helpers-api-catalog)
    * [⚡ `Update` Helpers (`HasUpdateHelpers`)](/guide/update-and-message-helpers#update-helpers-hasupdatehelpers)
    * [💬 `Message` Helpers (`HasMessageHelpers`)](/guide/update-and-message-helpers#message-helpers-hasmessagehelpers)
    * [👤 `Chat` & `User` Helpers (`HasChatHelpers` & `HasUserHelpers`)](/guide/update-and-message-helpers#chat-user-helpers-haschathelpers-hasuserhelpers)

### Conversational Flows
- [Flow & Interactive Screen Ecosystem](/guide/flow/): Multi-step dialogues and interactive bot screens (such as user onboarding wizards, settings panels, catalogs, e-commerce checkouts, surveys, and support ticket flows) are notoriously difficult to maintain when managed through scattered database flags, nested if/else statements, or naive polling handlers.
  - [🏛️ Two-Tier Architecture Comparison](/guide/flow/#two-tier-architecture-comparison)
  - [🧭 Flow Documentation Sitemap](/guide/flow/#flow-documentation-sitemap)
  - [⚡ Quickstart: Interactive Menu](/guide/flow/#quickstart-interactive-menu)
- [Conversational Flows (Linear Forms)](/guide/flow/conversational-flows): The base Tueen\Telegram\Flow\Flow class provides a linear state machine for multi-step textual dialogues, surveys, registration forms, and multi-prompt wizards.
  - [🏛️ Anatomy of a Conversational Flow](/guide/flow/conversational-flows#anatomy-of-a-conversational-flow)
  - [🧭 Step Navigation Methods](/guide/flow/conversational-flows#step-navigation-methods)
    * [`$this->to(string $stepMethod, array $data = []): static`](/guide/flow/conversational-flows#this-tostring-stepmethod-array-data-static)
    * [`$this->stay(?string $replyMessage = null, mixed $keyboard = null): static`](/guide/flow/conversational-flows#this-staystring-replymessage-null-mixed-keyboard-null-static)
    * [`$this->back(?string $replyMessage = null): static`](/guide/flow/conversational-flows#this-backstring-replymessage-null-static)
    * [`$this->finish(): void`](/guide/flow/conversational-flows#this-finish-void)
    * [`$this->cancel(?string $replyMessage = 'Operation cancelled.'): void`](/guide/flow/conversational-flows#this-cancelstring-replymessage-operation-cancelled-void)
  - [🎯 Filtering Allowed Updates (`allowedUpdates` & `#[AllowedUpdates]`)](/guide/flow/conversational-flows#filtering-allowed-updates-allowedupdates-allowedupdates)
    * [Using the `#[AllowedUpdates]` Attribute](/guide/flow/conversational-flows#using-the-allowedupdates-attribute)
    * [Using the `$allowedUpdates` Property or Method](/guide/flow/conversational-flows#using-the-allowedupdates-property-or-method)
    * [Global Default via Configuration](/guide/flow/conversational-flows#global-default-via-configuration)
  - [🕹️ External Flow Inspection & Control (`$bot->flow()`)](/guide/flow/conversational-flows#external-flow-inspection-control-bot-flow)
    * [The Fluent `FlowSession` Interface](/guide/flow/conversational-flows#the-fluent-flowsession-interface)
    * [Controlling Flows from Outside](/guide/flow/conversational-flows#controlling-flows-from-outside)
    * [Direct Facade Shortcuts on `$bot` & `$app`](/guide/flow/conversational-flows#direct-facade-shortcuts-on-bot-app)
- [Interactive Screens & Zero-Flicker Transitions](/guide/flow/interactive-screens): While standard Flow classes handle linear textual forms, InteractiveFlow is built for rich, menu-driven bots, dashboards, e-commerce product catalogs, and interactive control panels.
  - [⚡ Zero-Flicker In-Place Editing](/guide/flow/interactive-screens#zero-flicker-in-place-editing)
    * [Automatic Fallback Recovery](/guide/flow/interactive-screens#automatic-fallback-recovery)
  - [🖥️ The `Screen` Builder](/guide/flow/interactive-screens#the-screen-builder)
    * [Screen Builder Methods](/guide/flow/interactive-screens#screen-builder-methods)
  - [🔄 Refreshing Screens In-Place](/guide/flow/interactive-screens#refreshing-screens-in-place)
  - [🔔 Native Telegram Alerts & Toasts](/guide/flow/interactive-screens#native-telegram-alerts-toasts)
  - [📌 Sticky Screen / Pin to Bottom (`resendAtBottom`)](/guide/flow/interactive-screens#sticky-screen-pin-to-bottom-resendatbottom)
  - [🖼️ Media Screens (Photos, Videos, Animations)](/guide/flow/interactive-screens#media-screens-photos-videos-animations)
  - [⚠️ Confirmation Dialogs](/guide/flow/interactive-screens#confirmation-dialogs)
  - [☑️ Multi-Select Checklist Grid (`withChecklist`)](/guide/flow/interactive-screens#multi-select-checklist-grid-withchecklist)
    * [Toggling Checklist Items](/guide/flow/interactive-screens#toggling-checklist-items)
  - [🪜 Step Wizard & Progress Stepper (`withStepper`)](/guide/flow/interactive-screens#step-wizard-progress-stepper-withstepper)
    * [Supported Stepper Styles](/guide/flow/interactive-screens#supported-stepper-styles)
  - [📺 Single-Screen Support & `replaceFlow()`](/guide/flow/interactive-screens#single-screen-support-replaceflow)
    * [The `#[SingleScreen]` Attribute](/guide/flow/interactive-screens#the-singlescreen-attribute)
    * [Dedicated `$bot->replaceFlow()` API](/guide/flow/interactive-screens#dedicated-bot-replaceflow-api)
    * [Overriding at Runtime via `startFlow()`](/guide/flow/interactive-screens#overriding-at-runtime-via-startflow)
- [Lifecycle Hooks](/guide/flow/lifecycle-hooks): InteractiveFlow provides a predictable, component-based lifecycle. You can hook into each phase to load data, persist state, intercept exits, or update screens.
  - [🪝 Lifecycle Reference](/guide/flow/lifecycle-hooks#lifecycle-reference)
    * [`onCreate(): void`](/guide/flow/lifecycle-hooks#oncreate-void)
    * [`onStart(): void`](/guide/flow/lifecycle-hooks#onstart-void)
    * [`onResume(mixed $result = null): void`](/guide/flow/lifecycle-hooks#onresumemixed-result-null-void)
    * [`onPause(): void`](/guide/flow/lifecycle-hooks#onpause-void)
    * [`beforeRender(Screen $screen): void`](/guide/flow/lifecycle-hooks#beforerenderscreen-screen-void)
    * [`afterRender(mixed $sentMessage): void`](/guide/flow/lifecycle-hooks#afterrendermixed-sentmessage-void)
    * [`onUnhandled(Update $update): void`](/guide/flow/lifecycle-hooks#onunhandledupdate-update-void)
    * [`canInterrupt(Update $update): bool`](/guide/flow/lifecycle-hooks#caninterruptupdate-update-bool)
- [Keyboards & Action Binding](/guide/flow/keyboards-and-actions): InteractiveFlow decouples callback routing from tedious manual string checking using modern PHP 8 attributes: #[Action] and #[Input].
  - [🎯 The `#[Action]` Attribute](/guide/flow/keyboards-and-actions#the-action-attribute)
    * [1. Literal Action Patterns](/guide/flow/keyboards-and-actions#1-literal-action-patterns)
    * [2. Parameterized Action Patterns](/guide/flow/keyboards-and-actions#2-parameterized-action-patterns)
  - [✍️ Free-Text Inputs with `#[Input]`](/guide/flow/keyboards-and-actions#free-text-inputs-with-input)
  - [🎛️ Switching Keyboard Types Seamlessly](/guide/flow/keyboards-and-actions#switching-keyboard-types-seamlessly)
  - [📄 Automatic Pagination Bar](/guide/flow/keyboards-and-actions#automatic-pagination-bar)
  - [⏱️ Action Rate-Limiting & Debouncing (`#[Debounce]`)](/guide/flow/keyboards-and-actions#action-rate-limiting-debouncing-debounce)
  - [🛡️ Channel Membership Guard (`#[RequireMember]`)](/guide/flow/keyboards-and-actions#channel-membership-guard-requiremember)
    * [Guard Workflow:](/guide/flow/keyboards-and-actions#guard-workflow)
- [Navigation Stack & Root Flow](/guide/flow/navigation-and-stack): InteractiveFlow features a hierarchical navigation stack that models menus and multi-layered screens just like modern UI frameworks.
  - [🥞 Stack Navigation: `push()` and `pop()`](/guide/flow/navigation-and-stack#stack-navigation-push-and-pop)
    * [`$this->push(string $childFlowClass, array $data = []): void`](/guide/flow/navigation-and-stack#this-pushstring-childflowclass-array-data-void)
    * [`$this->pop(mixed $result = null): void`](/guide/flow/navigation-and-stack#this-popmixed-result-null-void)
  - [🧭 Navigation Buttons: `🔙` Back and `🏠` Home](/guide/flow/navigation-and-stack#navigation-buttons-back-and-home)
  - [🏠 Configuring `rootFlow` & Handling `/start`](/guide/flow/navigation-and-stack#configuring-rootflow-handling-start)
    * [Global `/start` Behavior](/guide/flow/navigation-and-stack#global-start-behavior)
  - [🍞 Breadcrumbs Trail (`withBreadcrumbs`)](/guide/flow/navigation-and-stack#breadcrumbs-trail-withbreadcrumbs)
  - [🛡️ Resilience & Missing Class Fallback](/guide/flow/navigation-and-stack#resilience-missing-class-fallback)
    * [1. Unwinding Navigation Stack to Parent Flows](/guide/flow/navigation-and-stack#1-unwinding-navigation-stack-to-parent-flows)
    * [2. Fallback to `rootFlow` (Default Flow)](/guide/flow/navigation-and-stack#2-fallback-to-rootflow-default-flow)
    * [3. Missing Step Recovery (`onMissingStep`)](/guide/flow/navigation-and-stack#3-missing-step-recovery-onmissingstep)
    * [4. Graceful Router Fallthrough](/guide/flow/navigation-and-stack#4-graceful-router-fallthrough)
- [State Storage Drivers](/guide/flow/state-storage): Flow sessions and interactive screen states are persisted between updates using pluggable state storage drivers.
  - [💾 Available Storage Drivers](/guide/flow/state-storage#available-storage-drivers)
    * [1. `FileStateStore` (Default for Webhooks)](/guide/flow/state-storage#1-filestatestore-default-for-webhooks)
    * [2. `MemoryStateStore` (Default for CLI Polling)](/guide/flow/state-storage#2-memorystatestore-default-for-cli-polling)
    * [3. `RedisStateStore` (High-Concurrency & Distributed)](/guide/flow/state-storage#3-redisstatestore-high-concurrency-distributed)
    * [4. `Psr16StateStore` (Framework Adapters)](/guide/flow/state-storage#4-psr16statestore-framework-adapters)

### Application & Production
- [Zero-Config App & Web Dashboard](/guide/app): Tueen\Telegram\App is the high-level application bootstrapper and orchestrator for tueen/telegram. It eliminates boilerplate configuration, automatically sets up file-based conversation flow storage, auto-discovers attribute controllers, and provides a built-in Web Setup Wizard and CLI tooling.
  - [🚀 1. The Single-File Entry Point](/guide/app#1-the-single-file-entry-point)
  - [⚡ 2. Adaptive Execution Environments](/guide/app#2-adaptive-execution-environments)
  - [🌐 3. Web Setup Wizard & Management Console](/guide/app#3-web-setup-wizard-management-console)
    * [1. First-Time Setup Wizard (When Token is Empty)](/guide/app#1-first-time-setup-wizard-when-token-is-empty)
    * [2. Live Management Console (When Configured)](/guide/app#2-live-management-console-when-configured)
    * [Securing the Dashboard](/guide/app#securing-the-dashboard)
  - [💾 4. Automatic Flow State Storage (`storage/flow`)](/guide/app#4-automatic-flow-state-storage-storageflow)
  - [📁 5. Automatic Controller Discovery](/guide/app#5-automatic-controller-discovery)
  - [🩺 6. System Diagnostics (`doctor`)](/guide/app#6-system-diagnostics-doctor)
  - [🧭 7. App & CLI API Reference](/guide/app#7-app-cli-api-reference)
    * [🏛️ `App` Class (`Tueen\Telegram\App`)](/guide/app#app-class-tueentelegramapp)
    * [💻 CLI Administrative Commands](/guide/app#cli-administrative-commands)
- [Pipeline & Middlewares](/guide/pipeline-middleware): Every outbound API request in tueen/telegram passes through an extensible onion middleware pipeline before reaching the underlying HTTP transport. This allows you to transparently handle retries, rate limits, request logging, tracing, and metric collection.
  - [⚡ 1. Native Built-In Middlewares](/guide/pipeline-middleware#1-native-built-in-middlewares)
    * [1. `RetryMiddleware`](/guide/pipeline-middleware#1-retrymiddleware)
    * [2. `RateLimitMiddleware`](/guide/pipeline-middleware#2-ratelimitmiddleware)
    * [3. `LoggingMiddleware`](/guide/pipeline-middleware#3-loggingmiddleware)
  - [🛠️ 2. Authoring Custom Middleware](/guide/pipeline-middleware#2-authoring-custom-middleware)
  - [🧭 3. Pipeline API Catalog](/guide/pipeline-middleware#3-pipeline-api-catalog)
    * [🧱 Pipeline Middlewares (`Tueen\Telegram\Pipeline\`)](/guide/pipeline-middleware#pipeline-middlewares-tueentelegrampipeline)
- [Error Handling & Lifecycle Hooks](/guide/error-handling-and-hooks): tueen/telegram provides a comprehensive, type-safe error handling architecture designed for PHP 8.4+ and PHP 8.5:
  - [1. Universal `ok()` / `isOk()` Check](/guide/error-handling-and-hooks#1-universal-ok-isok-check)
  - [2. Strongly-Typed Exceptions Hierarchy](/guide/error-handling-and-hooks#2-strongly-typed-exceptions-hierarchy)
    * [Catching Specific Exceptions](/guide/error-handling-and-hooks#catching-specific-exceptions)
  - [3. Typed Error Reasons (`TelegramErrorCode` Enum)](/guide/error-handling-and-hooks#3-typed-error-reasons-telegramerrorcode-enum)
  - [4. Error-Object Mode with Smart Helpers](/guide/error-handling-and-hooks#4-error-object-mode-with-smart-helpers)
  - [5. Catch All Errors (Including Network Errors)](/guide/error-handling-and-hooks#5-catch-all-errors-including-network-errors)
  - [6. Declarative `#[ApiErrors]` & Method Metadata](/guide/error-handling-and-hooks#6-declarative-apierrors-method-metadata)
  - [7. Lifecycle Event Hooks](/guide/error-handling-and-hooks#7-lifecycle-event-hooks)
  - [8. Incoming Update Error Handling (`catch` & `onUpdateError`)](/guide/error-handling-and-hooks#8-incoming-update-error-handling-catch-onupdateerror)
    * [Universal Catch](/guide/error-handling-and-hooks#universal-catch)
    * [Typed Catch (Specific Exception Filtering)](/guide/error-handling-and-hooks#typed-catch-specific-exception-filtering)
    * [Quick Reply Helper (`$bot->reply`)](/guide/error-handling-and-hooks#quick-reply-helper-bot-reply)
  - [🧭 9. Error Handling & Hooks API Catalog](/guide/error-handling-and-hooks#9-error-handling-hooks-api-catalog)
    * [🪝 Lifecycle Request Hooks (`Telegram`)](/guide/error-handling-and-hooks#lifecycle-request-hooks-telegram)
    * [🛡️ Incoming Update Exception Catchers (`Telegram`)](/guide/error-handling-and-hooks#incoming-update-exception-catchers-telegram)
- [Testing & Fakes](/guide/testing): Testing Telegram bots often poses challenges: calling real Telegram API servers during automated tests is slow, rate-limited, and may inadvertently message real users.
  - [🧪 1. Quick Example](/guide/testing#1-quick-example)
  - [🛠️ 2. Response Stubbing](/guide/testing#2-response-stubbing)
    * [Stubbing Successful Responses](/guide/testing#stubbing-successful-responses)
    * [Stubbing Telegram API Errors](/guide/testing#stubbing-telegram-api-errors)
  - [🔍 3. Inspecting Sent Requests](/guide/testing#3-inspecting-sent-requests)
  - [🧭 4. Testing & Fakes API Catalog](/guide/testing#4-testing-fakes-api-catalog)
    * [🛡️ Assertion Methods (`TelegramFake`)](/guide/testing#assertion-methods-telegramfake)
    * [🎭 Stubbing & Inspection Methods (`TelegramFake`)](/guide/testing#stubbing-inspection-methods-telegramfake)
- [Enums Reference](/guide/enums): tueen/telegram provides Backed Enums for Telegram Bot API string constants, ensuring type safety and IDE autocompletion.
  - [1. Core Telegram Enums](/guide/enums#1-core-telegram-enums)
    * [`ParseMode`](/guide/enums#parsemode)
    * [`ChatAction`](/guide/enums#chataction)
    * [`ChatType`](/guide/enums#chattype)
    * [`ChatMemberStatus`](/guide/enums#chatmemberstatus)
    * [`DiceEmoji`](/guide/enums#diceemoji)
    * [`ButtonStyle`](/guide/enums#buttonstyle)
    * [`BotCommandScopeType`](/guide/enums#botcommandscopetype)
    * [`PollType`](/guide/enums#polltype)
  - [2. Update & Message Enums](/guide/enums#2-update-message-enums)
    * [`UpdateType`](/guide/enums#updatetype)
    * [`MessageType`](/guide/enums#messagetype)
  - [3. Complete Enums Reference](/guide/enums#3-complete-enums-reference)

## Downloadable Packages, Full Context & Source Code
- [Download Complete Agent Skill ZIP](/tueen-telegram-bot-api-sdk.zip): Standalone skill folder (tueen-telegram-bot-api-sdk/) with SKILL.md and offline docs/.
- [Full Documentation (Single Context)](/llms-full.txt): Complete, concatenated markdown documentation for one-shot LLM ingestion.
- [GitHub Repository (Source Code, Tests & Examples)](https://github.com/tueen/telegram/): Official GitHub repository for source code inspection, test suites, and issue tracking when documentation is insufficient.