PHPackages                             chatflowphp/telegram - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. chatflowphp/telegram

ActiveLibrary[Utility & Helpers](/categories/utility)

chatflowphp/telegram
====================

Telegram adapter for the ChatFlow conversational runtime.

1.0.0(today)00MITPHPPHP ^8.2CI passing

Since Jun 22Pushed todayCompare

[ Source](https://github.com/chatflowphp/telegram)[ Packagist](https://packagist.org/packages/chatflowphp/telegram)[ Docs](https://github.com/chatflowphp/telegram)[ RSS](/packages/chatflowphp-telegram/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (5)Versions (2)Used By (0)

ChatFlow Telegram
=================

[](#chatflow-telegram)

[![CI](https://github.com/chatflowphp/telegram/actions/workflows/ci.yml/badge.svg)](https://github.com/chatflowphp/telegram/actions/workflows/ci.yml)[![PHPStan](https://camo.githubusercontent.com/b6d441ad4fe8332cb16c72aa27f22cc685181dfd74ae34964afc92c6c1146b3c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048505374616e2d6c6576656c2532306d61782d627269676874677265656e2e737667)](https://phpstan.org/)[![PHPUnit](https://camo.githubusercontent.com/bc004f75aacf2d6c71f73022452e7825ae8b775a86bc7c9826a7d07e5ab02279/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f504850556e69742d7465737465642d627269676874677265656e2e737667)](https://phpunit.de/)[![License: MIT](https://camo.githubusercontent.com/08cef40a9105b6526ca22088bc514fbfdbc9aac1ddbf8d4e6c750e3a88a44dca/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d626c75652e737667)](LICENSE)

`chatflowphp/telegram` is the Telegram adapter for the platform-neutral ChatFlow core.

It supports webhook and polling execution, commands, callback actions, smart render/edit-or-send behavior, media views, callback acknowledgements, Telegram file downloads and a typed Telegram layer for admin-style bots.

Full package documentation starts at [docs/index.md](docs/index.md). Use [docs/ai-index.md](docs/ai-index.md) as compact context for AI-assisted bot implementation tasks.

Start Here
----------

[](#start-here)

- Build your first bot: [docs/getting-started.md](docs/getting-started.md)
- Design a production bot: [docs/development/index.md](docs/development/index.md)
- Browse API and runtime reference: [docs/index.md](docs/index.md)
- AI implementation context: [docs/ai-index.md](docs/ai-index.md)

Quick Start
-----------

[](#quick-start)

```
use ChatFlow\Core\Context;
use ChatFlow\Telegram\Bot;
use ChatFlow\View\Action;
use ChatFlow\View\View;

$bot = new Bot($_ENV['TELEGRAM_BOT_TOKEN'], __DIR__);

$bot->command('start', static function (Context $ctx): void {
    $ctx->reply(
        View::text('Hello from ChatFlow Telegram')
            ->addActionRow(new Action('menu:open', 'Open menu'))
    );
});

$bot->prefix('menu:', static function (Context $ctx): void {
    $ctx->ack();
    $ctx->render(View::text('Menu opened'));
});

$bot->runWebhook();
```

For a runnable version of this pattern, see [examples/StarterBot](examples/StarterBot).

Mapping
-------

[](#mapping)

- Telegram messages become text events.
- Callback queries become action events.
- Chat id becomes `ConversationRef::getId()` and is used as the session key.
- Telegram message/callback metadata is stored in `MessageRef` for adapter delivery.
- `reply()` sends a new message.
- `render()` edits where possible, otherwise deletes/sends.
- `ack()` answers callback queries and falls back to a message when text is provided.

Telegram-Specific Layer
-----------------------

[](#telegram-specific-layer)

Keep portable handler code on `ChatFlow\Core\Context`. Use `ChatFlow\Telegram\TelegramContext` only when the flow needs Telegram-only behavior:

```
use ChatFlow\Telegram\TelegramContext;

$bot->command('ask', static function (TelegramContext $telegram): void {
    $telegram->forceReply('Send the updated post text');
});

$bot->onTelegramEvent('my_chat_member', static function (TelegramContext $telegram, array $update): void {
    $telegram->reply('Membership changed');
});
```

`TelegramContext` is intentionally not a facade for the Telegram Bot API. It only adds ChatFlow-aware Telegram helpers such as `forceReply()`, Telegram message options and current update metadata. Use core `ack()` for callback acknowledgements.

For publishing flows that need Telegram `message_id` immediately, inject `ChatFlow\Telegram\TelegramPublisher` and call `sendMessage()`, `sendMedia()`, `sendMediaGroup()`, `editText()`, `editCaption()` or `deleteMessage()` directly. Publisher methods return typed delivery results with chat id, message ids, endpoint and raw response. For Telegram Bot API endpoints not covered by ChatFlow semantics, inject `Telegram\Bot\Api` and use the SDK directly.

`TelegramView` and `TelegramMessageOptions` attach Telegram Bot API options to a neutral `View` via metadata:

```
use ChatFlow\Telegram\TelegramView;

$ctx->reply(TelegramView::forceReply('Reply with details'));
```

Long callback payloads are stored automatically behind short `cf:` callback data. Inbound callback queries are decoded back to the original action id and payload.

Inbound Telegram attachments are normalized for photos, documents, videos, animations, audio, voice, stickers and video notes. Telegram `file_id`, `file_unique_id`, captions, media group id, dimensions, duration, mime type and size are preserved in attachment metadata.

Media groups are collected by the adapter before core handling. The default collector waits briefly, aggregates updates with the same `media_group_id`, and emits one inbound event with ordered attachments.

`TelegramScreenManager` provides best-effort cleanup for command screens by tracking publisher delivery results and deleting previous message groups.

Operational Notes
-----------------

[](#operational-notes)

The default file-backed callback payload store keeps long callback payloads for 7 days and removes expired tokens opportunistically. The default media group store keeps pending album parts for 5 minutes and also cleans stale groups opportunistically.

Telegram `render()` is intentionally best-effort: the adapter tries to edit the current message, then falls back to delete/send or send-only when Telegram rejects the edit. These fallbacks are logged through the `Bot` logger but do not fail the flow unless final delivery also fails.

`StarterBot` is the minimal runnable onboarding example. `MiniShop` is the advanced Telegram-specific example with commands, inline callback buttons, smart edit-or-send rendering, media replies, scenes, validation and sessions.

```
php examples/StarterBot/mock.php
php examples/MiniShop/mock.php
```

Observability
-------------

[](#observability)

Pass `runtimeObserver` to the `Bot` constructor to receive core lifecycle events such as route matches, queued effects and delivery failures.

The MiniShop polling example enables JSONL runtime logs by default:

```
TELEGRAM_BOT_TOKEN=... php examples/MiniShop/run.php
tail -f storage/minishop/runtime.jsonl
```

Set `CHATFLOW_RUNTIME_LOG=/path/to/runtime.jsonl` to override the log path.

Documentation
-------------

[](#documentation)

### First Bot

[](#first-bot)

- [Getting Started](docs/getting-started.md)
- [Examples](docs/examples.md)
- [Testing](docs/testing.md)

### Production Workflow

[](#production-workflow)

- [Telegram Bot Development Kit](docs/development/index.md)
- [Bot Development Process](docs/development/development-process.md)
- [Bot Spec Template](docs/development/bot-spec-template.md)
- [Spec Review Checklist](docs/development/spec-review-checklist.md)
- [Implementation Blueprint Template](docs/development/implementation-blueprint-template.md)
- [Acceptance Testing Guide](docs/development/acceptance-testing-guide.md)
- [AI Development Workflow](docs/development/ai-development-workflow.md)

### API Reference

[](#api-reference)

- [Commands](docs/commands.md)
- [Callbacks](docs/callbacks.md)
- [Rendering](docs/rendering.md)
- [Telegram Context](docs/telegram-context.md)
- [Scenes And Dialogs](docs/scenes-dialogs.md)
- [Media And Files](docs/media-files.md)
- [Webhook And Polling](docs/webhook-polling.md)
- [AI Index](docs/ai-index.md)

License
-------

[](#license)

This project is released under the MIT License. See `LICENSE` for details.

###  Health Score

39

—

LowBetter than 85% of packages

Maintenance100

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity45

Maturing project, gaining track record

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

0d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/4216840?v=4)[webnarmin](/maintainers/webnarmin)[@webnarmin](https://github.com/webnarmin)

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/chatflowphp-telegram/health.svg)

```
[![Health](https://phpackages.com/badges/chatflowphp-telegram/health.svg)](https://phpackages.com/packages/chatflowphp-telegram)
```

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)