PHPackages                             lowel/telepath - 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. lowel/telepath

ActiveLibrary

lowel/telepath
==============

Telegram bot sdk for laravel inspired by phptg/bot-api

0.6.1(1mo ago)067[2 PRs](https://github.com/l0w3l/telepath/pulls)MITPHPPHP ^8.3CI passing

Since Jul 29Pushed 1mo agoCompare

[ Source](https://github.com/l0w3l/telepath)[ Packagist](https://packagist.org/packages/lowel/telepath)[ Docs](https://github.com/l0w3l/telepath)[ GitHub Sponsors](https://github.com/Lowel)[ RSS](/packages/lowel-telepath/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (16)Versions (27)Used By (0)

Telepath: Telegram bot SDK for Laravel
======================================

[](#telepath-telegram-bot-sdk-for-laravel)

[![Latest Version on Packagist](https://camo.githubusercontent.com/a02b2e669cc23022ec47d8d35fc5aae49e4ff3bc73b9729635374b0ac5a69e51/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6c6f77656c2f74656c65706174682e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/lowel/telepath)[![GitHub Tests Action Status](https://camo.githubusercontent.com/7480fb1d465258a86f888a7a4b79aeadec158f86a7c3d20bd831b58901e7a128/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6c3077336c2f74656c65706174682f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/l0w3l/telepath/actions?query=workflow%3Arun-tests+branch%3Amain)[![GitHub Code Style Action Status](https://camo.githubusercontent.com/0de19fb0df7b153986b711854674b8259dd1dd821ff7c433445afc27a74667ab/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6c3077336c2f74656c65706174682f6669782d7068702d636f64652d7374796c652d6973737565732e796d6c3f6272616e63683d6d61696e266c6162656c3d636f64652532307374796c65267374796c653d666c61742d737175617265)](https://github.com/l0w3l/telepath/actions?query=workflow%3A%22Fix+PHP+code+style+issues%22+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/3783614dfeb68a47982b24569c7b4fec6be725207195b3ce82e5343640f66947/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6c6f77656c2f74656c65706174682e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/lowel/telepath)

Telegram bot SDK for Laravel inspired by [phptg/bot-api](https://github.com/phptg/bot-api).

SDK supports routes and long pooling \\ webhook handling

How To Install
--------------

[](#how-to-install)

Install package via composer and publish config file:

```
composer require lowel/telepath
```

```
php artisan vendor:publish --tag="telepath-config"
```

Then you need to create *routes/telegram.php* file and provide bot key into your .env file:

```
touch routes/telegram.php
```

```
TELEPATH_TOKEN=

```

That's it! now you can handle Update request in your telegram.php file.

Usage
-----

[](#usage)

```
use Lowel\Telepath\Facades\Telepath;
use Phptg\BotApi\TelegramBotApi;
use Phptg\BotApi\Type\Update\Update;

Telepath::middleware(function (TelegramBotApi $telegramBotApi, Update $update, callable $callback) {
    logger()->info('Middleware in');
    $callback();
    logger()->info('Middleware out');
})->group(function () {
    Telepath::on(function (TelegramBotApi $telegramBotApi, Update $update) {
        $telegramBotApi->sendMessage($update->getMessage()->getChat()->getId(), 'Hello, world!');
    }, pattern: '/start');

    Telepath::on(function (TelegramBotApi $telegramBotApi, Update $update) {
        $message = $update->getMessage();
        if ($message) {
            $telegramBotApi->sendMessage($message->getChat()->getId(), $message->getText());
        }
    }, pattern: '/echo');
});
```

Start up:

```
php artisan telepath:run
```

Or using webhook:

```
php artisan telepath:hook:set https://your-domain.com/api/webhook
```

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

[](#documentation)

1. [Installation](#Installation)
2. [Configuration](#Configuration)
3. [Handlers](#Handlers)
4. [Conversations](#Conversations)
5. [Keyboards](#Keyboards)
6. [Exceptions](#Exceptions)
7. [Tests](#Tests)

### [Installation](#Documentation)

[](#installation)

You can install the package via composer and publish configuration file to your existing project:

```
composer require lowel/telepath
```

```
php artisan vendor:publish --tag="telepath-config"
```

Then you need to create *routes/telegram.php* file and provide bot key into your .env file:

```
touch routes/telegram.php
```

```
TELEPATH_TOKEN=

```

That's it! now you can handle Update request in your *telegram.php* file using [Telepath](src/Core/Router/TelegramRouterInterface.php) facade.

### [Configuration](#Documentation)

[](#configuration)

Below you can see how default configuration file looks like:

```
return [
    /*
    |--------------------------------------------------------------------------
    | Telepath Configuration
    |--------------------------------------------------------------------------
    |
    | This file is for storing the configuration of the Telepath package.
    | You can set your bot token and other settings here.
    |
    */

    'base_uri' => env('TELEPATH_BASE_URL', 'https://api.telegram.org'),
    'conversation' => [
        'ttl' => (int) env('TELEPATH_CONVERSATION_TIMEOUT', 60),
    ],

    /*
     * Routes path
     */
    'routes' => base_path(env('TELEPATH_ROUTES', 'routes/telegram.php')),

    'profile' => 'default',

    /**
     * see @link \Lowel\Telepath\Config\Profile
     */
    'profiles' => [
        'default' => [
            'token' => env('TELEPATH_TOKEN'),
            'offset' => (int) env('TELEPATH_OFFSET', 0),
            'limit' => (int) env('TELEPATH_LIMIT', 100),
            'timeout' => (int) env('TELEPATH_TIMEOUT', 30),
            'allowed_updates' => env('TELEPATH_ALLOWED_UPDATES', '*'),

            'whitelist' => env('TELEPATH_ADMINS', ''),
            'blacklist' => env('TELEPATH_BANNED', ''),

            // will send report about unhandled exceptions to the given chat_id instance (chat or dm)
            'chat_id_fallback' => (int) env('TELEPATH_CHAT_ID_FALLBACK', null),
        ],
    ],
];
```

The only one necessary thing is the *token* field. But lets try looks on all fields little closer:

- *base\_uri* - telegram api default domain (you can change if you are using [self-hosted solution](https://github.com/tdlib/telegram-bot-api));
- *conversation* - settings for dialog conversation that use memory to handle request in async mode:
    - *ttl* - decide how long conversation memory would work for each conversation message;
- *routes* - path to the routes handlers definition context (default *routes/telegram.php*);
- *profile* - default telegram bot profile name;
- *profiles* - list of telegram bot profiles;
    - *token* - telegram bot token that you receive from [@BotFather](https://t.me/BotFather) (REQUIRED, pass throw TELEPATH\_TOKEN env field);
    - *offset* - telegram getUpdates offset field (default 0);
    - *limit* - telegram getUpdates limit field (default 100);
    - *timeout* - telegram getUpdates timeout field (default 30);
    - *allowed\_updates* - telegram getUpdates allowed\_updates field (default '\*');
    - *whitelist* - comma separated list of user IDs that are allowed to interact with the bot (default empty);
    - *blacklist* - comma separated list of user IDs that are not allowed to interact with the bot (default empty);
    - *chat\_id\_fallback* - chat ID where unhandled exceptions will be reported (default null).

### [Handlers](#Documentation)

[](#handlers)

You can define handlers in your *routes/telegram.php* file using Telepath facade:

```
use Lowel\Telepath\Facades\Telepath;

Telepath::on(function (TelegramBotApi $telegramBotApi, Update $update) {
    $telegramBotApi->sendMessage($update->getMessage()->getChat()->getId(), 'Hello, world!');
}, pattern: '/start');
```

Also you can use middleware to handle request before and after main handler:

```
Telepath::middleware(function (TelegramBotApi $telegramBotApi, Update $update, callable $callback) {
    logger()->info('Middleware in');
    $callback();
    logger()->info('Middleware out');
})->group(function () {
    Telepath::on(function (TelegramBotApi $telegramBotApi, Update $update) {
        $telegramBotApi->sendMessage($update->getMessage()->getChat()->getId(), 'Hello, world!');
    }, pattern: '/start');
});
```

If you want to store Handlers and Middlewares as separated files you can generate them using commands below:

- Handlers

```
php artisan telepath:make:handler StartHandler
```

- Middlewares

```
php artisan telepath:make:middleware LogMiddleware
```

### [Conversations](#Conversations)

[](#conversations)

Conversations in Telepath simple as javascript Promises. You can generate a conversation using artisan:

```
php artisan telepath:make:conversation SampleConversation
```

And then use it in your handlers:

```
use Lowel\Telepath\Facades\Telepath;
use Phptg\BotApi\TelegramBotApi;
use Phptg\BotApi\Type\Update\Update;

Telepath::on(function (TelegramBotApi $telegramBotApi, Update $update) {
//
}, pattern: '/start-conversation')
    ->conversation(SampleConversation::class);
```

### [Keyboards](#Documentation)

[](#keyboards)

Telepath supports both inline and reply keyboards. You can create keyboards using the following artisan commands:

- Inline Keyboard

```
php artisan telepath:make:inline-keyboard SampleInlineKeyboard
```

- Reply Keyboard

```
php artisan telepath:make:reply-keyboard SampleReplyKeyboard
```

And then, after describing your keyboard layout in the generated files, you can use them in your handlers like this:

```
use Lowel\Telepath\Facades\Telepath;
use Phptg\BotApi\TelegramBotApi;
use Phptg\BotApi\Type\Update\Update;
use Lowel\Telepath\Keyboards\InlineKeyboard\SampleInlineKeyboard;

Telepath::on(function (TelegramBotApi $telegramBotApi, Update $update) {
    $keyboard = new SampleInlineKeyboard();
    $telegramBotApi->sendMessage(
        Extrasense::chat()->id,
        'Choose an option:',
        replyMarkup: $keyboard->make()->build()
    );
}, pattern: '/keyboard');

Telepath::keyboard(SampleInlineKeyboard::class);
```

### [Exceptions](#Documentation)

[](#exceptions)

Telepath has ExceptionHandler component. That allows you to catch unhandled exceptions and process them in your own way - just define wraps into your AppServiceProvider:

```
\Lowel\Telepath\Facades\Paranormal::wrap(function (Update $update, Throwable $e) {
    // Your code that may throw exceptions
})
```

By default Telepath will send unhandled exceptions report to the chat\_id defined in the configuration file.

### [Tests](#Documentation)

[](#tests)

I am strive to coverage my code as much as possible with tests. But its almost features tests only. I hope its will changed soon:

```
php artisan test
```

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

43

—

FairBetter than 90% of packages

Maintenance95

Actively maintained with recent releases

Popularity10

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity51

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 92.5% of commits — single point of failure

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

Every ~10 days

Total

23

Last Release

58d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/3d110b35da8c87d6303de59bdc352469c2b52c288091dd974beebf464c763fc8?d=identicon)[1ove1](/maintainers/1ove1)

---

Top Contributors

[![l0w3l](https://avatars.githubusercontent.com/u/83027906?v=4)](https://github.com/l0w3l "l0w3l (185 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (13 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (2 commits)")

---

Tags

laravelloweltelepath

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/lowel-telepath/health.svg)

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

###  Alternatives

[api-platform/core

Build a fully-featured hypermedia or GraphQL API in minutes!

2.6k48.1M235](/packages/api-platform-core)[shopware/platform

The Shopware e-commerce core

3.3k1.5M3](/packages/shopware-platform)[hirethunk/verbs

An event sourcing package that feels nice.

513162.9k6](/packages/hirethunk-verbs)[prestashop/prestashop

PrestaShop is an Open Source e-commerce platform, committed to providing the best shopping cart experience for both merchants and customers.

9.0k15.4k](/packages/prestashop-prestashop)[shopware/core

Shopware platform is the core for all Shopware ecommerce products.

595.2M386](/packages/shopware-core)[api-platform/symfony

Symfony API Platform integration

323.2M67](/packages/api-platform-symfony)

PHPackages © 2026

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