Download the PHP package vbespalov/laravel-telegram without Composer

Laravel Telegram

A typed Telegram Bot API 10.2 client for Laravel 10, 11, 12 and 13. The package contains request objects, response/input DTOs and typed methods for the complete Telegram Bot API contract.

The package is maintained by the cnxapp organization and is published as cnxapp/laravel-telegram under the Cnx\LaravelTelegram PHP namespace.

Requirements

• PHP 8.1+
• Laravel 10, 11, 12 or 13

Laravel 13 requires PHP 8.3 or newer; older supported Laravel versions retain the package's PHP 8.1 minimum.

Installation

The service provider is discovered automatically. Publish the configuration only when application-level overrides or multiple bots are needed:

Configure the default bot:

Sending messages

Constructor injection is the recommended API. Laravel resolves BotApiClient from the service container, and PhpStorm sees native request and response types:

The returned value is a generated Message DTO, so properties are typed:

Methods without parameters do not need a request object:

Using the BotApi facade

BotApi is the only supported facade. It has generated @method metadata for all Telegram methods and provides the same PhpStorm autocomplete as the injected client:

Prefer constructor injection in application services because dependencies are explicit and tests can replace BotApiClient without facade state.

Multiple bots

Add named configurations to config/telegram.php:

Select a bot for one request:

The selection resets to the default bot after every request, including failed requests. This makes the singleton client safe in long-lived queue workers.

Inline keyboards and nested DTOs

Nested Telegram objects are also typed:

Replies and message topics

Editing and deleting messages

editMessageText returns Message|bool, as defined by Telegram: a Message for a regular chat message and true for some inline-message operations.

Webhooks and incoming updates

Generated response DTOs can hydrate an incoming Telegram payload directly:

Optional Telegram fields are represented by null. DTO properties use camelCase while toArray() serializes them back to Telegram's snake_case field names:

Register a webhook with a typed request:

Uploading files

Direct and nested attach:// uploads are detected automatically:

In-memory uploads are supported as well:

Error handling

HTTP errors and Telegram API errors throw TelegramException:

Invalid or incomplete Telegram payloads throw an InvalidArgumentException during DTO hydration.

Raw API calls

call() is an escape hatch for a Telegram method newer than the pinned contract:

Use a generated method whenever it exists: generated calls provide request validation, response hydration and IDE types.

PhpStorm autocomplete

The package does not require an IDE helper:

• BotApiClient has 185 methods with native request and return types;
• every request DTO has typed named constructor parameters;
• every result DTO has typed readonly properties;
• the BotApi facade contains generated static method metadata;
• generated list and union return types are preserved in PHPDoc.

After installing or updating, let PhpStorm finish Composer indexing. If an already open project shows stale symbols, use File → Reload All from Disk. Invalidate caches only as a last resort.

API layout

• Requests: Cnx\LaravelTelegram\BotApi\Generated\Requests
• Types: Cnx\LaravelTelegram\BotApi\Generated\Types
• Client: Cnx\LaravelTelegram\BotApiClient
• Facade: Cnx\LaravelTelegram\Facades\BotApi
• Uploads: Cnx\LaravelTelegram\BotApi\InputFile
• Exceptions: Cnx\LaravelTelegram\Exceptions

The generated layer covers the complete Telegram Bot API 10.2 contract: 185 methods and 388 types.

Migrating from the legacy API

Version 3 removes the manually maintained API. The following classes no longer exist:

• Facades\Telegram
• TelegramApiClient
• MessageBuilder
• the old DTO and Enums namespaces

Replace the old facade and builder:

Replace method arguments with request DTOs:

Replace old DTO imports:

Legacy DTOs used Spatie\LaravelData\Optional for absent fields. Generated DTOs use nullable properties instead:

Applications still using the original package name must change both the Composer package and imports:

Regenerating the API

The pinned source manifest is resources/telegram-bot-api-10.2.json. Generated files are reproducible from the official documentation:

The generator refuses a source whose latest advertised Bot API version is not 10.2, preventing a newer contract from being silently published under the old version number. Generated files must not be edited manually.

Quality checks

The QA script runs Laravel Pint, Larastan at its maximum level and PHPUnit. The contract test verifies every type, field, union, method, parameter and return mapping in the pinned manifest.

Versioning

• Version 1: vbespalov/laravel-telegram and the Vbespalov\LaravelTelegram namespace.
• Version 2: package and namespace moved to cnxapp/Cnx, with the legacy API retained temporarily for migration.
• Version 3: only the generated, complete Bot API remains.

License

MIT