Laravel Telegram

Integração completa do Laravel 12 com o Telegram Bot API

Uma solução elegante e completa para integrar seu aplicativo Laravel com bots do Telegram, oferecendo suporte a webhooks, notificações, comandos personalizados, IA, conversas em etapas e muito mais.

Requisitos

• PHP 8.2 ou superior
• Laravel 12.x
• Token de bot do Telegram (obtenha através do @BotFather)

Instalação

1. Instale o pacote via Composer

composer require lucasgiovanni/laravel-telegram

2. Configure o pacote

Execute o comando de instalação:

php artisan telegram:install

Este comando irá:

• Publicar o arquivo de configuração config/telegram.php
• Solicitar seu token de bot do Telegram
• Adicionar as variáveis necessárias ao seu arquivo .env
• Publicar as migrações para as tabelas do Telegram

3. Execute as migrações para criar as tabelas necessárias

php artisan migrate

Funcionalidades

Envio de Mensagens

use LucasGiovanni\LaravelTelegram\Facades\Telegram;

// Mensagem de texto simples
Telegram::sendMessage($chatId, 'Olá, mundo!');

// Mensagem com formatação HTML
Telegram::sendMessage($chatId, '<b>Texto em negrito</b> e <i>itálico</i>', [
    'parse_mode' => 'HTML'
]);

// Enviar imagens
Telegram::sendPhoto($chatId, 'https://exemplo.com/imagem.jpg', 'Legenda da imagem');

// Enviar documentos
Telegram::sendDocument($chatId, '/caminho/para/arquivo.pdf', 'Documento importante');

// Enviar mensagens com botões inline
$keyboard = [
    [
        ['text' => 'Botão 1', 'callback_data' => 'botao_1'],
        ['text' => 'Botão 2', 'callback_data' => 'botao_2']
    ],
    [
        ['text' => 'Visite nosso site', 'url' => 'https://laravel.com']
    ]
];

Telegram::sendKeyboard($chatId, 'Escolha uma opção:', $keyboard);

Webhooks vs. Polling

Configurando um Webhook (recomendado para produção)

php artisan telegram:webhook https://seu-site.com/telegram/webhook

Isso configura o Telegram para enviar atualizações para sua aplicação automaticamente.

Executando em modo Polling

php artisan telegram:run

Este comando mantém o bot em execução, verificando novas mensagens periodicamente.

Notificações do Laravel

O pacote integra-se com o sistema de notificações do Laravel.

use Illuminate\Notifications\Notifiable;
use LucasGiovanni\LaravelTelegram\Notifications\TelegramNotification;

// Em seu modelo User ou outro modelo
class User extends Model
{
    use Notifiable;

    public function routeNotificationForTelegram()
    {
        return $this->telegram_chat_id;
    }
}

// Criar uma notificação
class NovoPedidoNotification extends TelegramNotification
{
    protected $pedido;

    public function __construct($pedido)
    {
        $this->pedido = $pedido;
    }

    public function toTelegram($notifiable)
    {
        return [
            'text' => "Novo pedido #{$this->pedido->id} recebido!",
            'keyboard' => [
                [['text' => 'Ver Pedido', 'url' => route('pedidos.show', $this->pedido->id)]]
            ]
        ];
    }
}

// Enviar a notificação
$user->notify(new NovoPedidoNotification($pedido));

// Ou sem um modelo
Notification::route('telegram', $chatId)
    ->notify(new NovoPedidoNotification($pedido));

Comandos

Os comandos são uma forma estruturada de responder a comandos específicos como /start ou /help.

// Registrar comandos no config/telegram.php
'commands' => [
    'start' => 'Iniciar interação com o bot',
    'help' => 'Exibir instruções de ajuda',
    'produtos' => 'Listar produtos disponíveis',
],

Conversas em Etapas

O pacote suporta conversas em múltiplas etapas para fluxos interativos.

use LucasGiovanni\LaravelTelegram\Conversations\Conversation;

class PedidoConversation extends Conversation
{
    protected function processStart(?string $message = null): void
    {
        $this->say("Olá! Vamos fazer seu pedido. Qual produto você deseja?");
        $this->state = 'awaitingProduct';
        $this->save();
    }

    protected function processAwaitingProduct(?string $message = null): void
    {
        // Salva o produto escolhido
        $this->data['produto'] = $message;
        
        // Pergunta a quantidade
        $this->say("Quantas unidades de {$message} você deseja?");
        $this->state = 'awaitingQuantity';
        $this->save();
    }

    protected function processAwaitingQuantity(?string $message = null): void
    {
        // Salva a quantidade
        $this->data['quantidade'] = (int) $message;
        
        // Finaliza o pedido
        $this->say("Obrigado! Seu pedido de {$this->data['quantidade']} unidades de {$this->data['produto']} foi registrado.");
        
        // Criar o pedido no banco de dados...
        
        // Finaliza a conversa
        $this->end();
    }
}

// Uso na aplicação:
$conversation = new PedidoConversation($telegram, $chatId);
$conversation->setUser($user)->start();

Integração com IA (Processamento de Linguagem Natural)

O pacote suporta integração com OpenAI para processamento de linguagem natural.

// Em config/telegram.php
'ai' => [
    'enabled' => true,
    'provider' => 'openai',
    'api_key' => env('OPENAI_API_KEY'),
    'model' => 'gpt-4o',
],

// No código
use LucasGiovanni\LaravelTelegram\Services\AIService;

$aiService = app(AIService::class);
$response = $aiService->processMessage($mensagem, $user, $chat);

Telegram::sendMessage($chatId, $response);

Armazenamento de Usuários e Mensagens

O pacote armazena automaticamente usuários, chats e mensagens do Telegram.

use LucasGiovanni\LaravelTelegram\Models\TelegramUser;
use LucasGiovanni\LaravelTelegram\Models\TelegramChat;
use LucasGiovanni\LaravelTelegram\Models\TelegramMessage;

// Buscar um usuário pelo ID do Telegram
$user = TelegramUser::where('telegram_id', $telegramId)->first();

// Verificar se o usuário está ativo
if ($user->isActive()) {
    // Usuário interagiu nos últimos 30 dias
}

// Obter mensagens recentes de um chat
$messages = TelegramChat::where('chat_id', $chatId)
    ->first()
    ->messages()
    ->orderBy('sent_at', 'desc')
    ->take(10)
    ->get();

Rate Limiting

Proteção automática contra limites de taxa da API do Telegram.

use LucasGiovanni\LaravelTelegram\Services\RateLimiter;

$rateLimiter = app(RateLimiter::class);

$rateLimiter->attempt('sendMessage', function() use ($telegram, $chatId, $message) {
    return $telegram->sendMessage($chatId, $message);
});

Templates de Mensagens

Sistema de templates para mensagens comuns com suporte a substituição de variáveis.

use LucasGiovanni\LaravelTelegram\Services\TemplateService;

// Renderizar template com variáveis
$message = TemplateService::render('welcome', [
    'name' => $user->first_name,
    'bot_name' => config('telegram.bot_name'),
]);

// Templates pré-definidos
$welcomeMessage = TemplateService::welcome($user);
$helpMessage = TemplateService::help();

Middlewares para Processamento de Mensagens

Filtragem e processamento de mensagens através de middlewares.

// Em config/telegram.php
'middlewares' => [
    \LucasGiovanni\LaravelTelegram\Middlewares\ValidateWebhook::class,
    \LucasGiovanni\LaravelTelegram\Middlewares\RateLimiter::class,
    \LucasGiovanni\LaravelTelegram\Middlewares\FilterMessages::class,
    \LucasGiovanni\LaravelTelegram\Middlewares\LogMessages::class,
    \App\Telegram\Middlewares\CustomMiddleware::class,
],

Comandos Artisan

O pacote inclui diversos comandos Artisan:

• telegram:install - Configura o pacote e o bot
• telegram:webhook {url} - Configura o webhook do bot
• telegram:webhook --remove - Remove o webhook configurado
• telegram:run - Executa o bot em modo polling
• telegram:publish - Publica arquivos de configuração e outros recursos

Personalizando o Comportamento

Você pode personalizar o comportamento do bot modificando o arquivo config/telegram.php:

// Em config/telegram.php
return [
    'token' => env('TELEGRAM_BOT_TOKEN', ''),
    'bot_name' => env('TELEGRAM_BOT_NAME', 'Laravel Bot'),
    'commands' => [
        'start' => 'Iniciar interação com o bot',
        'help' => 'Exibir instruções de ajuda',
        'custom' => 'Seu comando personalizado',
    ],
    'rate_limiting' => [
        'enabled' => true,
        'max_requests_per_minute' => 30,
    ],
    'conversations' => [
        'enabled' => true,
        'timeout' => 30, // minutos
    ],
    'ai' => [
        'enabled' => env('TELEGRAM_AI_ENABLED', false),
        'provider' => 'openai',
        'model' => 'gpt-4o',
    ],
    // ... mais opções disponíveis
];

Recursos Avançados

Bot Builder Visual

O pacote inclui um painel administrativo para construir fluxos de bot visualmente:

php artisan vendor:publish --tag=telegram-admin

# Acesse o painel em /telegram/admin

Sistema de Logs

Registros detalhados de todas as interações com o bot:

// Em app/Providers/AppServiceProvider.php
public function boot()
{
    Telegram::listenEvents(function ($event, $payload) {
        // Processar eventos do Telegram
        \Log::channel('telegram')->info("Evento {$event}", $payload);
    });
}

Contribuição

Contribuições são bem-vindas! Por favor, sinta-se à vontade para enviar um Pull Request.

Licença

Este pacote é um software de código aberto licenciado sob a licença MIT.