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

Documentation

1. Installation
2. Configuration
3. Handlers
4. Conversations
5. Keyboards
6. Exceptions
7. Tests

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.