Telegram Bot Bundle Laravel Package

Getting Started

Install the package via Composer:

composer require aymericcucherousset/telegram-bot-bundle

Publish the configuration file to customize bot settings:

php artisan vendor:publish --provider="AymericCucherousset\TelegramBotBundle\TelegramBotServiceProvider"

Register the bot token and webhook URL in .env:

TELEGRAM_BOT_TOKEN=your_bot_token_here
TELEGRAM_WEBHOOK_URL=https://yourdomain.com/telegram-webhook

Define a command handler by extending AymericCucherousset\TelegramBotBundle\Contracts\CommandHandler and binding it in AppServiceProvider:

$this->app->bind(
    'command:start',
    \App\Handlers\StartCommandHandler::class
);

Trigger the webhook listener via a route:

Route::post('/telegram-webhook', [\AymericCucherousset\TelegramBotBundle\Http\Controllers\TelegramWebhookController::class, 'handle']);

Implementation Patterns

Command Handling

Use the CommandHandler contract to process /start, /help, or custom commands:

namespace App\Handlers;

use AymericCucherousset\TelegramBotBundle\Contracts\CommandHandler;
use AymericCucherousset\TelegramBotBundle\Messages\Message;

class StartCommandHandler implements CommandHandler
{
    public function handle(string $command, Message $message): void
    {
        $message->reply('Welcome! Use /help for options.');
    }
}

Inline Keyboards

Create interactive buttons via InlineKeyboard:

use AymericCucherousset\TelegramBotBundle\Messages\InlineKeyboard;

$keyboard = new InlineKeyboard();
$keyboard->addRow(['Yes', 'No']);

$message->reply('Confirm?', $keyboard);

Middleware Integration

Extend the TelegramBotMiddleware to filter or modify incoming updates:

namespace App\Http\Middleware;

use AymericCucherousset\TelegramBotBundle\Middleware\TelegramBotMiddleware;

class CustomTelegramMiddleware extends TelegramBotMiddleware
{
    public function handle($request, Closure $next)
    {
        if ($request->input('message.text') === '/admin') {
            abort(403);
        }
        return parent::handle($request, $next);
    }
}

Sending Media

Attach photos, videos, or documents:

$message->sendPhoto('path/to/image.jpg', 'Caption here');
$message->sendDocument('path/to/file.pdf', 'Document title');

Gotchas and Tips

Webhook Configuration

• HTTPS Required: Telegram mandates HTTPS for webhooks. Use ngrok locally for testing.
• Verify Token: Always validate the update_id and message structure to avoid spoofing:

  if (!$request->has('update_id') || !$request->has('message')) {
      abort(400);
  }
  

Rate Limits

• Telegram enforces 30 requests/second per bot. Cache frequent responses or use queues:

  $message->reply('Processing...')->queue();
  

Debugging

• Enable debug mode in config (debug=true) to log raw updates:

  'debug' => env('TELEGRAM_DEBUG', false),
  

• Use dd($message->getUpdate()) to inspect raw payloads.

Extending Functionality

• Custom Updates: Extend AymericCucherousset\TelegramBotBundle\Updates\Update to handle non-command interactions (e.g., callbacks):

  $this->app->bind(
      'update:callback_query',
      \App\Handlers\CallbackHandler::class
  );
  

• Service Providers: Override the default TelegramBotServiceProvider for advanced use cases.

Common Pitfalls

• Webhook Missed Updates: If Telegram skips updates, re-register the webhook:

  $bot->setWebhook('https://yourdomain.com/telegram-webhook');
  

• Async Responses: Avoid blocking the webhook with long-running tasks; offload to queues.
• Message IDs: Reuse message_id for edits, but ensure the chat_id matches the original message.