README

Telegram bot SDK for Laravel inspired by phptg/bot-api.

SDK supports routes and long pooling \ webhook handling

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=<YOUR_TOKEN_HERE>

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

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

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=<YOUR_TOKEN_HERE>

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

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);
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 (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

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 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

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

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

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

The MIT License (MIT). Please see License File for more information.

lowel / telepath

Maintainers

Details