Create your Telegram Bot in 5 minutes with Laravel

0.7.0 2016-08-22 12:46 UTC

This package is not auto-updated.

Last update: 2021-04-07 02:08:31 UTC




Require this package, with Composer:

composer require black-river/telegram-bot

Add the service provider to the providers array of your config/app.php:



Publish the config file:

php artisan vendor:publish --provider="BlackRiver\TelegramBot\ServiceProvider"

Set environment variables in your .env:


To use a self-signed certificate, you should also specify the certificate path:



Define the default webhook route in your route file:

Route::post(config('telegram.token'), function (BlackRiver\TelegramBot\Bot $bot) {
  • Use the Bot's listen method to handle commands.

Set up the webhook url:

php artisan webhook:set

To ensure the bot is ready, send the /ping message:


To make sure there is no middleware or prefix that could "block" the default webhook route, check your app/Providers/RouteServiceProvider.php.

Webhook URL

You can change the default webhook route to your own:

Route::post('your-secret-path', function (BlackRiver\TelegramBot\Bot $bot) {
php artisan webhook:set your-secret-path

To remove the webhook integration, run php artisan webhook:remove.

Bot Commands

Create a new Bot Command in the app/Http/BotCommands directory:

php artisan make:bot-command NameCommand

Edit the handle method of app/Http/BotCommands/NameCommand.php:

$this->client->send('sendMessage', [
    'chat_id' => $this->request->json(''),
    'text' => 'Hello, '.trim($message),
  • Use the Client's send method to call any of the available methods.

  • Use the Client's save method to save Telegram files.

  • The Client and Request are available within a Command via $this->client and $this->request respectively.

Add the new command to the commands array of your config/telegram.php:

'/name' => App\Http\BotCommands\NameCommand::class,

Send the /name Johnny message:


Raw Webhook

Route::post('your-secret-path', function (Illuminate\Http\Request $request, BlackRiver\TelegramBot\Client $client) {
    // $bot->listen();

    $update = $request->json()->all();

    $client->send('sendMessage', [
        'chat_id' => $request->json(''),
        'text' => 'I\'ve got it!',


Add facades to the aliases array of your config/app.php:

'TelegramBot' => BlackRiver\TelegramBot\Facades\TelegramBot::class,
'TelegramApi' => BlackRiver\TelegramBot\Facades\TelegramApi::class,


Route::post('your-secret-path', function () {
    // TelegramBot::listen();

    TelegramApi::send('sendMessage', [
        'chat_id' => Request::json(''),
        'text' => 'Hey!',


Send a photo to your chat:

Route::post('photo', function (BlackRiver\TelegramBot\Client $client) {
    $client->send('sendPhoto', [
        'chat_id' => 'your-chat-id',
        'photo' => fopen(storage_path('photo.png'), 'r'),

Save incoming files:

Route::post('your-secret-path', function (Illuminate\Http\Request $request, BlackRiver\TelegramBot\Client $client) {
    $doc = $request->json('message.document');

    $filename = $doc['file_name'];

    $file = $client->send('getFile', ['file_id' => $doc['file_id']]);

    $client->save($file['result']['file_path'], storage_path($filename));


To extend the Client, add a new macro to the boot method of your app/Providers/AppServiceProvider.php:

    function ($chatId, \Illuminate\Http\UploadedFile $photo) {
        $saved = $photo->move(storage_path(), $photo->getClientOriginalName());

        $this->send('sendPhoto', [
            'chat_id' => $chatId,
            'photo' => fopen($saved->getRealPath(), 'r'),

Send an uploaded photo to your chat:

Route::post('upload', function (Illuminate\Http\Request $request, BlackRiver\TelegramBot\Client $client) {
    $client->sendUploadedPhoto('your-chat-id', $request->file('photo'));

Handle errors

The Client uses Guzzle Http Client to interact with Telegram API, so you can handle Guzzle Exceptions:

try {
    $client->send('methodName', []);
} catch (GuzzleHttp\Exception\ClientException $e) {
    // 400 level errors...
} catch (GuzzleHttp\Exception\ServerException $e) {
    // 500 level errors...
} catch (GuzzleHttp\Exception\RequestException $e) {
    // Connection timeout, DNS errors, etc.


Require this package, with Composer:

composer require black-river/telegram-bot

Add the service provider to the Register Service Providers section of your bootstrap/app.php:


Set the APP_URL, TELEGRAM_TOKEN and TELEGRAM_CERTIFICATE variables in your .env.

Copy the vendor's telegram.php config file to your config directory:

mkdir config/ && cp vendor/black-river/telegram-bot/config/telegram.php config/

Define the default webhook route in your route file:

$app->post(config('telegram.token'), function (BlackRiver\TelegramBot\Bot $bot) {


Laravel Telegram Bot is licensed under The MIT License (MIT).