Funcionalidade Laravel Telegram Bot

Guia completo para implementação do sistema de Telegram Webhook em Laravel, baseado no projeto Rei do Óleo. Este sistema inclui processamento de mensagens, validação de webhooks, tratamento de erros e sistema de comandos unificado.

implementar telegram webhook laravel completo

Antes de implementar, certifique-se de ter:

• Laravel 12 instalado
• PHP 8.2+ configurado
• Composer para dependências
• Redis para cache (recomendado)
• Bot Token do Telegram configurado
• Webhook URL configurada

O sistema será implementado com a seguinte estrutura:

app/
├── Http/
│   ├── Controllers/Api/
│   │   ├── TelegramWebhookController.php
│   │   └── TelegramStatsController.php
│   ├── Middleware/
│   │   ├── TelegramWebhookSecretMiddleware.php
│   │   ├── TelegramWebhookExceptionHandler.php
│   │   └── TelegramWebhookLoggingMiddleware.php
│   ├── Requests/
│   │   ├── TelegramWebhookRequest.php
│   │   └── TelegramWebhookSetupRequest.php
│   └── Resources/
│       └── TelegramWebhookResource.php
├── Services/
│   ├── TelegramWebhookService.php
│   ├── TelegramBotService.php
│   ├── TelegramMessageProcessorService.php
│   └── Telegram/
│       ├── TelegramWebhookValidationService.php
│       └── TelegramMessageProcessorService.php
└── Console/Commands/
    └── TestTelegramWebhook.php

1. Configurar variáveis de ambiente (.env):

TELEGRAM_ENABLED=true
TELEGRAM_BOT_TOKEN=seu_bot_token_aqui
TELEGRAM_WEBHOOK_SECRET=seu_secret_aqui
TELEGRAM_RECIPIENTS=123456789,987654321

2. Configurar services.php:

'telegram' => [
    'enabled' => env('TELEGRAM_ENABLED', false),
    'bot_token' => env('TELEGRAM_BOT_TOKEN'),
    'webhook_secret' => env('TELEGRAM_WEBHOOK_SECRET', ''),
    'recipients' => explode(',', env('TELEGRAM_RECIPIENTS', '')),
],

Próximos passos serão adicionados gradualmente…

• [ ] Laravel 12 instalado
• [ ] PHP 8.2+ configurado
• [ ] Redis configurado
• [ ] Bot Token do Telegram obtido
• [ ] Webhook URL configurada

• [ ] Configurar variáveis de ambiente
• [ ] Implementar Controllers
• [ ] Implementar Services
• [ ] Implementar Middlewares
• [ ] Implementar Requests
• [ ] Implementar Resources
• [ ] Configurar rotas
• [ ] Implementar testes

• [ ] Testar webhook
• [ ] Validar processamento de mensagens
• [ ] Verificar logs
• [ ] Testar comandos

1. Webhook não recebe mensagens:

• Verificar se a URL está correta
• Verificar se o bot token está válido
• Verificar logs do Laravel

2. Erro de validação:

• Verificar estrutura do payload
• Verificar regras de validação
• Verificar logs de erro

3. Comandos não funcionam:

• Verificar sistema de comandos
• Verificar autorização do usuário
• Verificar logs de processamento

As próximas seções serão adicionadas gradualmente:

• Seção 1: Controllers e Rotas
• Seção 2: Services e Processamento
• Seção 3: Middlewares e Validação
• Seção 4: Requests e Resources
• Seção 5: Testes e Comandos
• Seção 6: Scripts de Instalação

<?php
 
namespace App\Contracts;
 
use Illuminate\Http\Request;
 
interface LoggingServiceInterface
{
    /**
     * Log API requests and responses
     */
    public function logApiRequest(Request $request, array $context = []): void;
 
    /**
     * Log API responses
     */
    public function logApiResponse(int $statusCode, array $response, float $duration, array $context = []): void;
 
    /**
     * Log business operations
     */
    public function logBusinessOperation(string $operation, array $data, string $status = 'success', array $context = []): void;
 
    /**
     * Log security events
     */
    public function logSecurityEvent(string $event, array $data, string $level = 'warning', array $context = []): void;
 
    /**
     * Log performance metrics
     */
    public function logPerformance(string $operation, float $duration, array $metrics = [], array $context = []): void;
 
    /**
     * Log audit trail
     */
    public function logAudit(string $action, string $model, int $modelId, array $changes = [], array $context = []): void;
 
    /**
     * Log Telegram bot events
     */
    public function logTelegramEvent(string $event, array $data, string $level = 'info', array $context = []): void;
 
    /**
     * Log WhatsApp events
     */
    public function logWhatsAppEvent(string $event, array $data, string $level = 'info', array $context = []): void;
 
    /**
     * Log exceptions with context
     */
    public function logException(\Throwable $exception, array $context = []): void;
 
    /**
     * Get log statistics
     */
    public function getLogStats(): array;
}

<?php
 
namespace App\Services;
 
use App\Contracts\LoggingServiceInterface;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\Facades\Auth;
use Illuminate\Http\Request;
use Spatie\Activitylog\ActivityLogger;
 
class LoggingService implements LoggingServiceInterface
{
    /**
     * Log API requests and responses
     */
    public function logApiRequest(Request $request, array $context = []): void
    {
        $logData = array_merge([
            'request_id' => uniqid('api_', true),
            'method' => $request->method(),
            'url' => $request->fullUrl(),
            'ip' => $request->ip(),
            'user_agent' => $request->userAgent(),
            'user_id' => $request->user()?->id,
            'headers' => $this->sanitizeHeaders($request->headers->all()),
            'timestamp' => now()->toISOString(),
        ], $context);
 
        if ($request->method() !== 'GET') {
            $logData['body'] = $this->sanitizeBody($request->all());
        }
 
        Log::channel('api')->info('API Request', $logData);
    }
 
    /**
     * Log API responses
     */
    public function logApiResponse(int $statusCode, array $response, float $duration, array $context = []): void
    {
        $logData = array_merge([
            'status_code' => $statusCode,
            'duration_ms' => round($duration, 2),
            'response_size' => strlen(json_encode($response)),
            'timestamp' => now()->toISOString(),
        ], $context);
 
        if ($statusCode >= 400) {
            $logData['error_response'] = $response;
            Log::channel('api')->error('API Error Response', $logData);
        } else {
            Log::channel('api')->info('API Response', $logData);
        }
    }
 
    /**
     * Log business operations
     */
    public function logBusinessOperation(string $operation, array $data, string $status = 'success', array $context = []): void
    {
        $logData = array_merge([
            'operation' => $operation,
            'status' => $status,
            'user_id' => Auth::id(),
            'timestamp' => now()->toISOString(),
        ], $data, $context);
 
        Log::channel('business')->info('Business Operation', $logData);
    }
 
    /**
     * Log security events
     */
    public function logSecurityEvent(string $event, array $data, string $level = 'warning', array $context = []): void
    {
        $logData = array_merge([
            'event' => $event,
            'level' => $level,
            'user_id' => Auth::id(),
            'ip' => request()->ip(),
            'user_agent' => request()->userAgent(),
            'timestamp' => now()->toISOString(),
        ], $data, $context);
 
        Log::channel('security')->$level('Security Event', $logData);
    }
 
    /**
     * Log performance metrics
     */
    public function logPerformance(string $operation, float $duration, array $metrics = [], array $context = []): void
    {
        $logData = array_merge([
            'operation' => $operation,
            'duration_ms' => round($duration, 2),
            'memory_usage' => memory_get_usage(true),
            'memory_peak' => memory_get_peak_usage(true),
            'timestamp' => now()->toISOString(),
        ], $metrics, $context);
 
        Log::channel('performance')->info('Performance Metric', $logData);
    }
 
    /**
     * Log audit trail
     */
    public function logAudit(string $action, string $model, int $modelId, array $changes = [], array $context = []): void
    {
        $logData = array_merge([
            'action' => $action,
            'model' => $model,
            'model_id' => $modelId,
            'changes' => $changes,
            'user_id' => Auth::id(),
            'timestamp' => now()->toISOString(),
        ], $context);
 
        Log::channel('audit')->info('Audit Trail', $logData);
    }
 
    /**
     * Log Telegram bot events
     */
    public function logTelegramEvent(string $event, array $data, string $level = 'info', array $context = []): void
    {
        $logData = array_merge([
            'event' => $event,
            'level' => $level,
            'timestamp' => now()->toISOString(),
        ], $data, $context);
 
        Log::channel('telegram')->$level('Telegram Event', $logData);
    }
 
    /**
     * Log WhatsApp events
     */
    public function logWhatsAppEvent(string $event, array $data, string $level = 'info', array $context = []): void
    {
        $logData = array_merge([
            'event' => $event,
            'level' => $level,
            'timestamp' => now()->toISOString(),
        ], $data, $context);
 
        Log::channel('whatsapp')->$level('WhatsApp Event', $logData);
    }
 
    /**
     * Log exceptions with context
     */
    public function logException(\Throwable $exception, array $context = []): void
    {
        $logData = array_merge([
            'exception' => get_class($exception),
            'message' => $exception->getMessage(),
            'file' => $exception->getFile(),
            'line' => $exception->getLine(),
            'trace' => $exception->getTraceAsString(),
            'user_id' => Auth::id(),
            'timestamp' => now()->toISOString(),
        ], $context);
 
        Log::channel('errors')->error('Exception', $logData);
    }
 
    /**
     * Get log statistics
     */
    public function getLogStats(): array
    {
        return [
            'channels' => ['api', 'business', 'security', 'performance', 'audit', 'telegram', 'whatsapp', 'errors'],
            'timestamp' => now()->toISOString(),
        ];
    }
 
    /**
     * Sanitize headers for logging
     */
    private function sanitizeHeaders(array $headers): array
    {
        $sensitiveHeaders = ['authorization', 'cookie', 'x-api-key', 'x-csrf-token'];
 
        foreach ($sensitiveHeaders as $header) {
            if (isset($headers[$header])) {
                $headers[$header] = ['***REDACTED***'];
            }
        }
 
        return $headers;
    }
 
    /**
     * Sanitize request body for logging
     */
    private function sanitizeBody(array $body): array
    {
        $sensitiveFields = ['password', 'token', 'secret', 'key', 'api_key'];
 
        foreach ($sensitiveFields as $field) {
            if (isset($body[$field])) {
                $body[$field] = '***REDACTED***';
            }
        }
 
        return $body;
    }
}

<?php
 
namespace App\Contracts;
 
interface MessageFlowTrackerInterface
{
    // Core tracking methods
    public function trackMethod(string $className, string $methodName, array $inputData = [], array $outputData = []): void;
    public function endMethod(string $className, string $methodName, array $outputData = []): void;
 
    // Report generation
    public function generateFlowReport(array $payload): string;
    public function generateUserReport(array $payload): string;
 
    // Pipeline control
    public function startTracking(string $messageId): void;
    public function endTracking(): void;
    public function clearTrace(): void;
 
    // Data retrieval
    public function getExecutedMethods(): array;
    public function getExpectedMethods(): array;
    public function getMethodData(): array;
 
    // Utility methods
    public function identifyMessageType(array $payload): string;
    public function saveTrace(): void;
    public function isEnabled(): bool;
}

<?php
 
namespace App\Services;
 
use App\Contracts\MessageFlowTrackerInterface;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\Facades\Cache;
 
class MessageFlowTrackerService implements MessageFlowTrackerInterface
{
    private array $executedMethods = [];
    private array $expectedMethods = [];
    private array $methodData = [];
    private array $timestamps = [];
    private string $messageId;
    private bool $isEnabled;
 
    public function __construct()
    {
        $this->isEnabled = config('message-flow.enabled', false);
        $this->messageId = uniqid('msg_', true);
 
        // Define o fluxo esperado para cada tipo de mensagem
        $this->expectedMethods = [
            'text' => [
                'TelegramMessageProcessorService.processWebhookPayload',
                'TelegramMessageProcessorService.processTextMessage',
                'TelegramBotService.processMessage',
                'TelegramChannel.sendMessageWithKeyboard'
            ],
            'voice' => [
                'TelegramMessageProcessorService.processWebhookPayload',
                'TelegramMessageProcessorService.processVoiceMessage',
                'SpeechToTextService.convertVoiceToText',
                'TelegramBotService.processMessage',
                'TelegramChannel.sendMessageWithKeyboard'
            ],
            'callback_query' => [
                'TelegramMessageProcessorService.processWebhookPayload',
                'TelegramMessageProcessorService.processCallbackQuery',
                'TelegramBotService.processCallbackQuery',
                'TelegramChannel.sendTextMessage'
            ]
        ];
    }
 
    /**
     * Track method execution
     */
    public function trackMethod(string $className, string $methodName, array $inputData = [], array $outputData = []): void
    {
        if (!$this->isEnabled) {
            return;
        }
 
        $methodKey = "{$className}.{$methodName}";
        $this->executedMethods[] = $methodKey;
        $this->timestamps[$methodKey] = microtime(true);
        $this->methodData[$methodKey] = [
            'input' => $inputData,
            'output' => $outputData,
            'timestamp' => now()->toISOString()
        ];
    }
 
    /**
     * End method tracking
     */
    public function endMethod(string $className, string $methodName, array $outputData = []): void
    {
        if (!$this->isEnabled) {
            return;
        }
 
        $methodKey = "{$className}.{$methodName}";
 
        if (isset($this->methodData[$methodKey])) {
            $this->methodData[$methodKey]['output'] = $outputData;
            $this->methodData[$methodKey]['duration'] = microtime(true) - $this->timestamps[$methodKey];
        }
    }
 
    /**
     * Generate flow report
     */
    public function generateFlowReport(array $payload): string
    {
        if (!$this->isEnabled) {
            return 'Message flow tracking is disabled';
        }
 
        $messageType = $this->identifyMessageType($payload);
        $expected = $this->expectedMethods[$messageType] ?? [];
        $missing = array_diff($expected, $this->executedMethods);
        $extra = array_diff($this->executedMethods, $expected);
 
        $report = "=== MESSAGE FLOW REPORT ===\n";
        $report .= "Message Type: {$messageType}\n";
        $report .= "Message ID: {$this->messageId}\n";
        $report .= "Executed Methods: " . count($this->executedMethods) . "\n";
        $report .= "Expected Methods: " . count($expected) . "\n";
        $report .= "Missing Methods: " . count($missing) . "\n";
        $report .= "Extra Methods: " . count($extra) . "\n\n";
 
        if (!empty($missing)) {
            $report .= "MISSING METHODS:\n";
            foreach ($missing as $method) {
                $report .= "  - {$method}\n";
            }
            $report .= "\n";
        }
 
        if (!empty($extra)) {
            $report .= "EXTRA METHODS:\n";
            foreach ($extra as $method) {
                $report .= "  - {$method}\n";
            }
            $report .= "\n";
        }
 
        return $report;
    }
 
    /**
     * Generate user-friendly report
     */
    public function generateUserReport(array $payload): string
    {
        if (!$this->isEnabled) {
            return 'Tracking disabled';
        }
 
        $messageType = $this->identifyMessageType($payload);
        $expected = $this->expectedMethods[$messageType] ?? [];
        $missing = array_diff($expected, $this->executedMethods);
 
        if (empty($missing)) {
            return "✅ Message processed successfully through all expected steps";
        }
 
        $report = "⚠️ Message processing incomplete:\n";
        $report .= "Missing steps: " . count($missing) . "\n";
 
        foreach ($missing as $method) {
            $report .= "• " . str_replace('.', ' → ', $method) . "\n";
        }
 
        return $report;
    }
 
    /**
     * Start tracking
     */
    public function startTracking(string $messageId): void
    {
        $this->messageId = $messageId;
        $this->clearTrace();
    }
 
    /**
     * End tracking
     */
    public function endTracking(): void
    {
        if ($this->isEnabled) {
            $this->saveTrace();
        }
    }
 
    /**
     * Clear trace
     */
    public function clearTrace(): void
    {
        $this->executedMethods = [];
        $this->methodData = [];
        $this->timestamps = [];
    }
 
    /**
     * Get executed methods
     */
    public function getExecutedMethods(): array
    {
        return $this->executedMethods;
    }
 
    /**
     * Get expected methods
     */
    public function getExpectedMethods(): array
    {
        return $this->expectedMethods;
    }
 
    /**
     * Get method data
     */
    public function getMethodData(): array
    {
        return $this->methodData;
    }
 
    /**
     * Identify message type
     */
    public function identifyMessageType(array $payload): string
    {
        if (isset($payload['callback_query'])) {
            return 'callback_query';
        }
 
        if (isset($payload['message'])) {
            $message = $payload['message'];
 
            if (isset($message['text'])) {
                return 'text';
            }
            if (isset($message['voice'])) {
                return 'voice';
            }
            if (isset($message['audio'])) {
                return 'audio';
            }
        }
 
        return 'unknown';
    }
 
    /**
     * Save trace to cache
     */
    public function saveTrace(): void
    {
        if (!$this->isEnabled) {
            return;
        }
 
        try {
            $traceData = [
                'message_id' => $this->messageId,
                'executed_methods' => $this->executedMethods,
                'method_data' => $this->methodData,
                'timestamp' => now()->toISOString()
            ];
 
            Cache::put("message_trace_{$this->messageId}", $traceData, 60); // 1 hour
        } catch (\Exception $e) {
            Log::error('Failed to save message trace', [
                'error' => $e->getMessage(),
                'message_id' => $this->messageId
            ]);
        }
    }
 
    /**
     * Check if tracking is enabled
     */
    public function isEnabled(): bool
    {
        return $this->isEnabled;
    }
}

<?php
 
namespace App\Contracts;
 
interface NotificationChannelInterface
{
    /**
     * Send text message
     *
     * @param string $message
     * @param string|null $recipient
     * @return array
     */
    public function sendTextMessage(string $message, ?string $recipient = null): array;
 
    /**
     * Send notification with data
     *
     * @param array $data
     * @return array
     */
    public function sendNotification(array $data): array;
 
    /**
     * Test connection
     *
     * @return array
     */
    public function testConnection(): array;
 
    /**
     * Get channel name
     *
     * @return string
     */
    public function getChannelName(): string;
 
    /**
     * Check if channel is enabled
     *
     * @return bool
     */
    public function isEnabled(): bool;
}

<?php
 
namespace App\Contracts;
 
/**
 * Interface para métodos de tracking de mensagens
 * Esta interface define os métodos que devem estar disponíveis
 * para qualquer classe que precise rastrear execução de métodos
 */
interface MessageTrackingInterface
{
    /**
     * Inicia o tracking de um método
     */
    public function trackMethod(string $methodName, array $inputData = [], array $outputData = []): void;
 
    /**
     * Finaliza o tracking de um método
     */
    public function endMethod(string $methodName, array $outputData = []): void;
 
    /**
     * Inicializa o sistema de tracking
     */
    public function initializeTracking(): void;
}

<?php
// app/Providers/LoggingServiceProvider.php
 
namespace App\Providers;
 
use Illuminate\Support\ServiceProvider;
use App\Contracts\LoggingServiceInterface;
use App\Services\LoggingService;
 
class LoggingServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->app->bind(LoggingServiceInterface::class, LoggingService::class);
    }
 
    public function boot(): void
    {
        // Publish configuration if needed
    }
}

<?php
// app/Providers/MessageFlowServiceProvider.php
 
namespace App\Providers;
 
use App\Contracts\MessageFlowTrackerInterface;
use App\Services\MessageFlowTrackerService;
use Illuminate\Support\ServiceProvider;
 
class MessageFlowServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->app->singleton(MessageFlowTrackerInterface::class, MessageFlowTrackerService::class);
    }
 
    public function boot(): void
    {
        // Publish configuration if needed
    }
}

// Adicionar no array 'providers' do config/app.php
 
'providers' => [
    // ... outros providers
    App\Providers\LoggingServiceProvider::class,
    App\Providers\MessageFlowServiceProvider::class,
    // ... outros providers
],

<?php
 
return [
    // ... outras configurações
 
    'telegram' => [
        'enabled' => env('TELEGRAM_ENABLED', false),
        'bot_token' => env('TELEGRAM_BOT_TOKEN'),
        'webhook_secret' => env('TELEGRAM_WEBHOOK_SECRET', ''),
        'recipients' => array_filter(explode(',', env('TELEGRAM_RECIPIENTS', ''))),
    ],
 
    // ... outras configurações
];

# ============================================================================
# TELEGRAM BOT CONFIGURATION
# ============================================================================
 
# Enable/Disable Telegram Bot
TELEGRAM_ENABLED=true
 
# Bot Token from @BotFather
TELEGRAM_BOT_TOKEN=your_bot_token_here
 
# Webhook Secret for Security (optional but recommended)
TELEGRAM_WEBHOOK_SECRET=your_webhook_secret_here
 
# Recipients (Chat IDs separated by commas)
TELEGRAM_RECIPIENTS=123456789,987654321
 
# ============================================================================
# MESSAGE FLOW TRACKING CONFIGURATION
# ============================================================================
 
# Enable/Disable Message Flow Tracking
MESSAGE_FLOW_TRACKING_ENABLED=true
 
# Output Configuration
MESSAGE_FLOW_SEND_TO_USER=true
MESSAGE_FLOW_LOG_TO_FILE=true
MESSAGE_FLOW_CACHE_TRACES=true
 
# Performance Thresholds (milliseconds)
MESSAGE_FLOW_SLOW_THRESHOLD=100
MESSAGE_FLOW_VERY_SLOW_THRESHOLD=500
 
# Memory Thresholds (MB)
MESSAGE_FLOW_MEMORY_WARNING=50
MESSAGE_FLOW_MEMORY_CRITICAL=100
 
# Storage TTL (minutes)
MESSAGE_FLOW_CACHE_TTL=1440
MESSAGE_FLOW_DB_TTL=10080

<?php
 
return [
    // ... outras configurações
 
    'channels' => [
        // ... outros canais
 
        'api' => [
            'driver' => 'daily',
            'path' => storage_path('logs/api.log'),
            'level' => 'info',
            'days' => 30,
        ],
 
        'business' => [
            'driver' => 'daily',
            'path' => storage_path('logs/business.log'),
            'level' => 'info',
            'days' => 90,
        ],
 
        'security' => [
            'driver' => 'daily',
            'path' => storage_path('logs/security.log'),
            'level' => 'warning',
            'days' => 365,
        ],
 
        'performance' => [
            'driver' => 'daily',
            'path' => storage_path('logs/performance.log'),
            'level' => 'info',
            'days' => 30,
        ],
 
        'audit' => [
            'driver' => 'daily',
            'path' => storage_path('logs/audit.log'),
            'level' => 'info',
            'days' => 365,
        ],
 
        'telegram' => [
            'driver' => 'daily',
            'path' => storage_path('logs/telegram.log'),
            'level' => 'info',
            'days' => 30,
        ],
 
        'whatsapp' => [
            'driver' => 'daily',
            'path' => storage_path('logs/whatsapp.log'),
            'level' => 'info',
            'days' => 30,
        ],
 
        'errors' => [
            'driver' => 'daily',
            'path' => storage_path('logs/errors.log'),
            'level' => 'error',
            'days' => 30,
        ],
    ],
];

<?php
 
namespace App\Services;
 
use App\Contracts\LoggingServiceInterface;
use App\Contracts\MessageFlowTrackerInterface;
use App\Contracts\MessageTrackingInterface;
use App\Services\Channels\TelegramChannel;
 
class TelegramMessageProcessorService implements MessageTrackingInterface
{
    public function __construct(
        private TelegramBotService $telegramBotService,
        private TelegramChannel $telegramChannel,
        private LoggingServiceInterface $loggingService,
        private MessageFlowTrackerInterface $flowTracker,
        private ?SpeechToTextService $speechService = null
    ) {
        $this->initializeTracking();
    }
 
    /**
     * Process webhook payload
     */
    public function processWebhookPayload(array $payload): array
    {
        // Inicia tracking
        $this->trackMethod('processWebhookPayload', ['payload' => $payload]);
 
        try {
            // Check if it's a callback query (button click)
            if (isset($payload['callback_query'])) {
                $result = $this->processCallbackQuery($payload['callback_query']);
                $this->endMethod('processWebhookPayload', ['result' => $result]);
                return $result;
            }
 
            // Verify if it's a message
            if (!isset($payload['message'])) {
                $result = [
                    'success' => false,
                    'status' => 'ignored',
                    'message' => 'No message in payload'
                ];
 
                $this->endMethod('processWebhookPayload', ['result' => $result]);
                return $result;
            }
 
            $message = $payload['message'];
 
            // Process different message types
            if (isset($message['text'])) {
                $result = $this->processTextMessage($message);
                $this->endMethod('processWebhookPayload', ['result' => $result]);
                return $result;
            }
 
            if (isset($message['voice'])) {
                $result = $this->processVoiceMessage($message);
                $this->endMethod('processWebhookPayload', ['result' => $result]);
                return $result;
            }
 
            if (isset($message['audio'])) {
                $result = $this->processAudioMessage($message);
                $this->endMethod('processWebhookPayload', ['result' => $result]);
                return $result;
            }
 
            $result = $this->createIgnoredResult('Unsupported message type');
            $this->endMethod('processWebhookPayload', ['result' => $result]);
            return $result;
 
        } catch (\Exception $e) {
            $result = [
                'success' => false,
                'status' => 'error',
                'message' => 'Internal server error',
                'error' => $e->getMessage()
            ];
 
            $this->endMethod('processWebhookPayload', ['result' => $result, 'error' => $e->getMessage()]);
 
            $this->loggingService->logException($e, [
                'operation' => 'telegram_webhook_processing',
                'payload' => $payload
            ]);
 
            return $result;
        }
    }
 
    /**
     * Process text message
     */
    private function processTextMessage(array $message): array
    {
        $this->trackMethod('processTextMessage', ['message' => $message]);
 
        $result = $this->telegramBotService->processMessage($message);
        $result['status'] = 'success';
        $result['message'] = 'Text message processed';
        $result['input_type'] = 'text';
 
        $this->endMethod('processTextMessage', ['result' => $result]);
        return $result;
    }
 
    /**
     * Process voice message
     */
    private function processVoiceMessage(array $message): array
    {
        $this->trackMethod('processVoiceMessage', ['message' => $message]);
 
        try {
            $chatId = $message['chat']['id'];
 
            if (!$this->speechService) {
                $result = $this->createIgnoredResult('Speech service not available');
                $this->endMethod('processVoiceMessage', ['result' => $result]);
                return $result;
            }
 
            // Convert voice to text
            $voiceFileId = $message['voice']['file_id'];
            $text = $this->speechService->convertVoiceToText($voiceFileId);
 
            if (empty($text)) {
                $result = $this->createIgnoredResult('Could not convert voice to text');
                $this->endMethod('processVoiceMessage', ['result' => $result]);
                return $result;
            }
 
            // Process the converted text as a regular message
            $textMessage = array_merge($message, ['text' => $text]);
            $result = $this->processTextMessage($textMessage);
            $result['input_type'] = 'voice';
            $result['converted_text'] = $text;
 
            $this->endMethod('processVoiceMessage', ['result' => $result]);
            return $result;
 
        } catch (\Exception $e) {
            $result = [
                'success' => false,
                'status' => 'error',
                'message' => 'Voice processing failed',
                'error' => $e->getMessage()
            ];
 
            $this->endMethod('processVoiceMessage', ['result' => $result, 'error' => $e->getMessage()]);
            return $result;
        }
    }
 
    /**
     * Process audio message
     */
    private function processAudioMessage(array $message): array
    {
        $this->trackMethod('processAudioMessage', ['message' => $message]);
 
        try {
            $chatId = $message['chat']['id'];
 
            if (!$this->speechService) {
                $result = $this->createIgnoredResult('Speech service not available');
                $this->endMethod('processAudioMessage', ['result' => $result]);
                return $result;
            }
 
            // Convert audio to text
            $audioFileId = $message['audio']['file_id'];
            $text = $this->speechService->convertAudioToText($audioFileId);
 
            if (empty($text)) {
                $result = $this->createIgnoredResult('Could not convert audio to text');
                $this->endMethod('processAudioMessage', ['result' => $result]);
                return $result;
            }
 
            // Process the converted text as a regular message
            $textMessage = array_merge($message, ['text' => $text]);
            $result = $this->processTextMessage($textMessage);
            $result['input_type'] = 'audio';
            $result['converted_text'] = $text;
 
            $this->endMethod('processAudioMessage', ['result' => $result]);
            return $result;
 
        } catch (\Exception $e) {
            $result = [
                'success' => false,
                'status' => 'error',
                'message' => 'Audio processing failed',
                'error' => $e->getMessage()
            ];
 
            $this->endMethod('processAudioMessage', ['result' => $result, 'error' => $e->getMessage()]);
            return $result;
        }
    }
 
    /**
     * Process callback query
     */
    private function processCallbackQuery(array $callbackQuery): array
    {
        $this->trackMethod('processCallbackQuery', ['callback_query' => $callbackQuery]);
 
        $result = $this->telegramBotService->processCallbackQuery($callbackQuery);
        $result['status'] = 'success';
        $result['message'] = 'Callback query processed';
        $result['input_type'] = 'callback_query';
 
        $this->endMethod('processCallbackQuery', ['result' => $result]);
        return $result;
    }
 
    /**
     * Create ignored result
     */
    private function createIgnoredResult(string $message): array
    {
        return [
            'success' => false,
            'status' => 'ignored',
            'message' => $message,
            'type' => 'ignored'
        ];
    }
 
    // ========================================
    // MessageTrackingInterface Implementation
    // ========================================
 
    /**
     * Inicializa o sistema de tracking
     */
    public function initializeTracking(): void
    {
        // Tracking já é inicializado no construtor
    }
 
    /**
     * Inicia o tracking de um método
     */
    public function trackMethod(string $methodName, array $inputData = [], array $outputData = []): void
    {
        $className = class_basename($this);
        $this->flowTracker->trackMethod($className, $methodName, $inputData, $outputData);
    }
 
    /**
     * Finaliza o tracking de um método
     */
    public function endMethod(string $methodName, array $outputData = []): void
    {
        $className = class_basename($this);
        $this->flowTracker->endMethod($className, $methodName, $outputData);
    }
}

Continue para a próxima seção quando estiver pronto!

<?php
 
namespace App\Services\Telegram;
 
use App\Services\Telegram\Commands\UnifiedCommandSystem;
use App\Services\Telegram\Commands\CommandResult;
use App\Services\Channels\TelegramChannel;
use App\Services\SpeechToTextService;
use App\Contracts\LoggingServiceInterface;
 
class TelegramMessageProcessorService
{
    public function __construct(
        private UnifiedCommandSystem $commandSystem,
        private TelegramAuthorizationService $authorizationService,
        private ?SpeechToTextService $speechService = null,
        private ?TelegramChannel $telegramChannel = null,
        private ?LoggingServiceInterface $loggingService = null
    ) {}
 
    public function processMessage(array $payload): array
    {
        try {
            // Check if it's a callback query (button click)
            if (isset($payload['callback_query'])) {
                return $this->processCallbackQuery($payload['callback_query']);
            }
 
            // Verify if it's a message
            if (!isset($payload['message'])) {
                $result = [
                    'success' => false,
                    'status' => 'ignored',
                    'message' => 'No message in payload'
                ];
 
                return $result;
            }
 
            $message = $payload['message'];
 
            // Process different message types
            if (isset($message['text'])) {
                return $this->processTextMessage($message);
            }
 
            if (isset($message['voice'])) {
                return $this->processVoiceMessage($message);
            }
 
            if (isset($message['audio'])) {
                return $this->processAudioMessage($message);
            }
 
            return $this->createIgnoredResult('Unsupported message type');
 
        } catch (\Exception $e) {
            $result = [
                'success' => false,
                'status' => 'error',
                'message' => 'Internal server error',
                'error' => $e->getMessage()
            ];
 
            if ($this->loggingService) {
                $this->loggingService->logException($e, [
                    'operation' => 'telegram_webhook_processing',
                    'payload' => $payload
                ]);
            }
 
            return $result;
        }
    }
 
    private function processTextMessage(array $message): array
    {
        $chatId = $message['chat']['id'];
        $text = $message['text'] ?? '';
 
        if (empty($text)) {
            return $this->createEmptyMessageResponse($chatId);
        }
 
        // Process command through unified system
        $result = $this->commandSystem->processCommand($text, $this->getContextFromMessage($message));
 
        if ($result->isSuccess()) {
            return $this->createSuccessResponse($chatId, $result);
        } else {
            return $this->createCommandNotFoundResponse($chatId, $result);
        }
    }
 
    private function processVoiceMessage(array $message): array
    {
        try {
            $chatId = $message['chat']['id'];
            $voice = $message['voice'];
 
            // Check if speech service is available
            if (!$this->speechService) {
                if ($this->telegramChannel) {
                    $this->telegramChannel->sendTextMessage(
                        "❌ Serviço de reconhecimento de voz não está disponível. Envie uma mensagem de texto.",
                        (string) $chatId
                    );
                }
 
                return $this->createVoiceConversionErrorResponse($chatId);
            }
 
            // Send processing message
            if ($this->telegramChannel) {
                $this->telegramChannel->sendTextMessage(
                    "🎤 Processando mensagem de voz...",
                    (string) $chatId
                );
            }
 
            // Download voice file
            $voiceFilePath = $this->downloadVoiceFile($voice['file_id']);
 
            if (!$voiceFilePath) {
                return $this->createVoiceConversionErrorResponse($chatId);
            }
 
            // Convert voice to text with error handling
            try {
                $text = $this->speechService->convertVoiceToText($voiceFilePath);
            } catch (\Exception $speechException) {
                if ($this->loggingService) {
                    $this->loggingService->logException($speechException, [
                        'operation' => 'speech_to_text_conversion',
                        'chat_id' => $chatId,
                        'file_path' => $voiceFilePath
                    ]);
                }
 
                // Send error message to user
                if ($this->telegramChannel) {
                    $this->telegramChannel->sendTextMessage(
                        "❌ Erro ao processar mensagem de voz. Tente novamente ou envie uma mensagem de texto.",
                        (string) $chatId
                    );
                }
 
                return $this->createVoiceConversionErrorResponse($chatId);
            }
 
            if (!$text) {
                if ($this->loggingService) {
                    $this->loggingService->logException(new \Exception('Failed to convert voice to text'), [
                        'chat_id' => $chatId,
                        'file_path' => $voiceFilePath
                    ]);
                }
 
                // Send error message to user
                if ($this->telegramChannel) {
                    $this->telegramChannel->sendTextMessage(
                        "❌ Não foi possível reconhecer o texto da mensagem de voz. Tente novamente.",
                        (string) $chatId
                    );
                }
 
                return $this->createVoiceConversionErrorResponse($chatId);
            }
 
            // Clean up voice file
            if (file_exists($voiceFilePath)) {
                unlink($voiceFilePath);
            }
 
            // Send recognized text to user
            if ($this->telegramChannel) {
                $this->telegramChannel->sendTextMessage(
                    "🎯 Texto reconhecido: *{$text}*",
                    (string) $chatId
                );
            }
 
            // Update context for voice processing
            $context = $this->getContextFromMessage($message);
            $context['type'] = 'voice';
            $context['original_voice'] = $text;
 
            // Process converted text through unified system
            $result = $this->commandSystem->processCommand($text, $context);
 
            if ($result->isSuccess()) {
                return $this->createSuccessResponse($chatId, $result);
            } else {
                return $this->createCommandNotFoundResponse($chatId, $result);
            }
 
        } catch (\Exception $e) {
            if ($this->loggingService) {
                $this->loggingService->logException($e, [
                    'operation' => 'voice_message_processing',
                    'chat_id' => $message['chat']['id'] ?? null,
                    'message' => $message
                ]);
            }
 
            return $this->createVoiceConversionErrorResponse($chatId);
        }
    }
 
    private function processCallbackQuery(array $callbackQuery): array
    {
        $chatId = $callbackQuery['message']['chat']['id'] ?? 0;
        $callbackData = $callbackQuery['data'] ?? '';
 
        if (empty($callbackData)) {
            return $this->createEmptyCallbackResponse($chatId);
        }
 
        // Process callback through unified system
        $result = $this->commandSystem->processCommand($callbackData, $this->getContextFromCallbackQuery($callbackQuery));
 
        if ($result->isSuccess()) {
            return $this->createSuccessResponse($chatId, $result);
        } else {
            return $this->createCallbackErrorResponse($chatId, $result);
        }
    }
 
    private function getContextFromMessage(array $message): array
    {
        // Check if this is a callback query
        if (isset($message['callback_query'])) {
            return $this->getContextFromCallbackQuery($message['callback_query']);
        }
 
        // Regular message
        return [
            'chat_id' => $message['chat']['id'],
            'user_id' => $message['from']['id'] ?? null,
            'type' => $this->determineMessageType($message),
            'timestamp' => $message['date'] ?? time(),
            'user_permissions' => $this->getUserPermissions($message)
        ];
    }
 
    private function getContextFromCallbackQuery(array $callbackQuery): array
    {
        return [
            'chat_id' => $callbackQuery['message']['chat']['id'] ?? 0,
            'user_id' => $callbackQuery['from']['id'] ?? null,
            'type' => 'callback_query',
            'timestamp' => $callbackQuery['date'] ?? time(),
            'user_permissions' => $this->getUserPermissions($callbackQuery)
        ];
    }
 
    private function determineMessageType(array $message): string
    {
        if (isset($message['callback_query'])) {
            return 'callback_query';
        }
 
        if (isset($message['voice'])) {
            return 'voice';
        }
 
        if (isset($message['audio'])) {
            return 'audio';
        }
 
        if (isset($message['text'])) {
            return 'text';
        }
 
        return 'unknown';
    }
 
    private function getUserPermissions(array $message): array
    {
        // Extract user permissions from message or callback query
        $userId = null;
 
        if (isset($message['from']['id'])) {
            // Regular message
            $userId = $message['from']['id'];
        } elseif (isset($message['callback_query']['from']['id'])) {
            // Callback query wrapped in payload
            $userId = $message['callback_query']['from']['id'];
        }
 
        if (!$userId) {
            return ['user'];
        }
 
        // TODO: Implement actual permission checking
        // For now, return default permissions
        return ['user'];
    }
 
    private function createSuccessResponse(int $chatId, CommandResult $result): array
    {
        $data = $result->getData();
 
        return [
            'success' => true,
            'chat_id' => $chatId,
            'type' => $result->getType(),
            'data' => $data,
            'command_info' => $result->getCommandMatch() ? [
                'command_id' => $result->getCommandMatch()->getCommand()->getId(),
                'confidence' => $result->getCommandMatch()->getConfidence()
            ] : null
        ];
    }
 
    private function createCommandNotFoundResponse(int $chatId, CommandResult $result): array
    {
        $data = $result->getData();
        $fallbackMessage = $data['fallback_message'] ?? 'Comando não encontrado';
 
        // Send the fallback message to the user in Telegram chat
        if ($this->telegramChannel) {
            $this->telegramChannel->sendTextMessage(
                $fallbackMessage,
                (string) $chatId
            );
        }
 
        return [
            'success' => false,
            'chat_id' => $chatId,
            'type' => 'command_not_found',
            'message' => $fallbackMessage,
            'suggestions' => $data['suggestions'] ?? [],
            'data' => $data
        ];
    }
 
    private function createEmptyMessageResponse(int $chatId): array
    {
        return [
            'success' => false,
            'chat_id' => $chatId,
            'type' => 'empty_message',
            'message' => 'Mensagem vazia recebida.',
            'data' => []
        ];
    }
 
    private function createVoiceConversionErrorResponse(int $chatId): array
    {
        return [
            'success' => false,
            'chat_id' => $chatId,
            'type' => 'voice_conversion_error',
            'message' => 'Erro ao converter mensagem de voz.',
            'data' => []
        ];
    }
 
    private function createEmptyCallbackResponse(int $chatId): array
    {
        return [
            'success' => false,
            'chat_id' => $chatId,
            'type' => 'empty_callback',
            'message' => 'Dados de callback vazios.',
            'data' => []
        ];
    }
 
    private function createCallbackErrorResponse(int $chatId, CommandResult $result): array
    {
        return [
            'success' => false,
            'chat_id' => $chatId,
            'type' => 'callback_error',
            'message' => 'Erro ao processar callback.',
            'data' => $result->getData()
        ];
    }
 
    private function createIgnoredResult(string $message): array
    {
        return [
            'success' => false,
            'status' => 'ignored',
            'message' => $message
        ];
    }
 
    // Additional methods for audio processing and file downloads...
    // (processAudioMessage, downloadVoiceFile, downloadAudioFile, etc.)
}

<?php
 
namespace App\Repositories;
 
use Illuminate\Support\Facades\Config;
use Illuminate\Support\Facades\Cache;
 
class TelegramRepository
{
    private const CACHE_TTL = 3600; // 1 hour
    private const CACHE_PREFIX = 'telegram:';
 
    /**
     * Get authorized users
     */
    public function getAuthorizedUsers(): array
    {
        return Config::get('services.telegram.recipients', []);
    }
 
    /**
     * Check if user is authorized
     */
    public function isUserAuthorized(int $chatId): bool
    {
        $authorizedUsers = $this->getAuthorizedUsers();
        return in_array($chatId, $authorizedUsers);
    }
 
    /**
     * Get bot configuration
     */
    public function getBotConfig(): array
    {
        return [
            'enabled' => Config::get('services.telegram.enabled', false),
            'bot_token' => Config::get('services.telegram.bot_token'),
            'recipients' => $this->getAuthorizedUsers(),
        ];
    }
 
    /**
     * Cache webhook info
     */
    public function cacheWebhookInfo(array $webhookInfo): void
    {
        Cache::put(
            self::CACHE_PREFIX . 'webhook_info',
            $webhookInfo,
            self::CACHE_TTL
        );
    }
 
    /**
     * Get cached webhook info
     */
    public function getCachedWebhookInfo(): ?array
    {
        return Cache::get(self::CACHE_PREFIX . 'webhook_info');
    }
 
    /**
     * Clear webhook cache
     */
    public function clearWebhookCache(): void
    {
        Cache::forget(self::CACHE_PREFIX . 'webhook_info');
    }
 
    /**
     * Cache message processing result
     */
    public function cacheMessageResult(int $chatId, array $result): void
    {
        $key = self::CACHE_PREFIX . "message_result:{$chatId}";
        Cache::put($key, $result, self::CACHE_TTL);
    }
 
    /**
     * Get cached message result
     */
    public function getCachedMessageResult(int $chatId): ?array
    {
        $key = self::CACHE_PREFIX . "message_result:{$chatId}";
        return Cache::get($key);
    }
 
    /**
     * Store webhook log
     */
    public function storeWebhookLog(array $payload, array $result): void
    {
        $logData = [
            'timestamp' => now()->toISOString(),
            'payload' => $payload,
            'result' => $result,
            'ip' => request()->ip(),
            'user_agent' => request()->userAgent(),
        ];
 
        // Store in cache for recent logs
        $logs = Cache::get(self::CACHE_PREFIX . 'recent_logs', []);
        $logs[] = $logData;
 
        // Keep only last 100 logs
        if (count($logs) > 100) {
            $logs = array_slice($logs, -100);
        }
 
        Cache::put(self::CACHE_PREFIX . 'recent_logs', $logs, self::CACHE_TTL);
    }
 
    /**
     * Get recent webhook logs
     */
    public function getRecentWebhookLogs(int $limit = 50): array
    {
        $logs = Cache::get(self::CACHE_PREFIX . 'recent_logs', []);
        return array_slice($logs, -$limit);
    }
 
    /**
     * Get webhook statistics
     */
    public function getWebhookStats(): array
    {
        $logs = $this->getRecentWebhookLogs(1000);
 
        $stats = [
            'total_requests' => count($logs),
            'successful_requests' => 0,
            'failed_requests' => 0,
            'ignored_requests' => 0,
            'message_requests' => 0,
            'callback_requests' => 0,
        ];
 
        foreach ($logs as $log) {
            $result = $log['result'] ?? [];
            $status = $result['status'] ?? 'unknown';
 
            switch ($status) {
                case 'success':
                    $stats['successful_requests']++;
                    break;
                case 'error':
                    $stats['failed_requests']++;
                    break;
                case 'ignored':
                    $stats['ignored_requests']++;
                    break;
            }
 
            // Count request types
            if (isset($log['payload']['message'])) {
                $stats['message_requests']++;
            }
            if (isset($log['payload']['callback_query'])) {
                $stats['callback_requests']++;
            }
        }
 
        return $stats;
    }
}

<?php
 
namespace App\Http\Controllers\Api;
 
use App\Http\Controllers\Controller;
use App\Http\Requests\TelegramWebhookRequest;
use App\Http\Requests\TelegramWebhookSetupRequest;
use App\Http\Resources\TelegramWebhookResource;
use App\Services\TelegramBotService;
use App\Services\TelegramWebhookService;
use App\Services\Telegram\TelegramMessageProcessorService;
use App\Services\Telegram\TelegramWebhookValidationService;
use App\Services\Channels\TelegramChannel;
use App\Contracts\LoggingServiceInterface;
use App\Contracts\MessageFlowTrackerInterface;
use Illuminate\Http\JsonResponse;
 
class TelegramWebhookController extends Controller
{
    public function __construct(
        private TelegramBotService $telegramBotService,
        private TelegramChannel $telegramChannel,
        private TelegramWebhookService $webhookService,
        private TelegramMessageProcessorService $messageProcessor,
        private TelegramWebhookValidationService $webhookValidationService,
        private LoggingServiceInterface $loggingService,
        private MessageFlowTrackerInterface $flowTracker
    ) {}
 
    /**
     * Handle Telegram webhook
     */
    public function handle(TelegramWebhookRequest $request): JsonResponse
    {
        $startTime = microtime(true);
 
        // Inicializa o tracker com ID único
        $this->flowTracker->startTracking(uniqid('webhook_', true));
 
        try {
            // Check if validation failed
            if ($request->has('validation_errors')) {
                $validationErrors = $request->input('validation_errors');
                $errorMessage = $this->createValidationErrorMessage($validationErrors);
 
                // Send friendly error message to user via Telegram
                $this->sendFriendlyErrorMessage($request->all(), $errorMessage);
 
                return TelegramWebhookResource::ignored('Validation failed - friendly message sent to user')
                    ->response()
                    ->setStatusCode(200);
            }
 
            $payload = $request->validated();
 
            // Validate payload structure first
            $validation = $this->webhookService->validatePayload($payload);
 
            if (!$validation['valid']) {
                // Send friendly error message to user via Telegram
                $this->sendFriendlyErrorMessage($payload, $validation['message']);
 
                return TelegramWebhookResource::ignored($validation['message'])
                    ->response()
                    ->setStatusCode(200);
            }
 
            // Validate webhook and mark as processing (after payload validation)
            $updateId = $payload['update_id'] ?? null;
            $skipDuplicateCheck = app()->environment('testing');
            if (!$this->webhookValidationService->validateAndMarkProcessing($updateId, $skipDuplicateCheck)) {
                return TelegramWebhookResource::success('Duplicate webhook ignored', [
                    'success' => true,
                    'status' => 'ignored',
                    'message' => 'Duplicate webhook ignored',
                    'update_id' => $updateId
                ])
                    ->response()
                    ->setStatusCode(200);
            }
 
            // Process the webhook payload with timeout protection
            $result = $this->processWithTimeout(function () use ($payload) {
                return $this->messageProcessor->processWebhookPayload($payload);
            }, 25); // 25 seconds timeout
 
            // Gera relatório do fluxo APÓS o processamento
            $flowReport = $this->flowTracker->generateFlowReport($payload);
            $userReport = $this->flowTracker->generateUserReport($payload);
 
            // Finaliza o tracking
            $this->flowTracker->endTracking();
 
            // Se habilitado, envia relatório para o usuário
            if (config('message-flow.tracking.send_to_user', false)) {
                $this->sendFlowReportToUser($payload, $userReport);
            }
 
            if (config('message-flow.enabled', false)) {
                $this->loggingService->logTelegramEvent('message_flow_report', [
                    'flow_report' => $flowReport,
                    'user_report' => $userReport,
                    'payload' => $payload
                ], 'info');
            }
 
            // Check if the result is valid and has the expected structure
            if (!is_array($result) || !isset($result['success'])) {
                $this->loggingService->logTelegramEvent('telegram_webhook_invalid_result', [
                    'error' => 'Invalid result structure from message processor',
                    'result' => $result,
                    'payload' => $payload,
                    'telegram_update_id' => $request->input('update_id'),
                    'timestamp' => now()->toISOString()
                ], 'error');
 
                // Send friendly error message to user
                $this->sendFriendlyErrorMessage($payload, 'Desculpe, ocorreu um erro interno. Tente novamente em alguns instantes.');
 
                return TelegramWebhookResource::error('Invalid processing result')
                    ->response()
                    ->setStatusCode(500);
            }
 
            // Check if this is a normal response (not an error) - check status first
            $isNormalResponse = isset($result['type']) && in_array($result['type'], [
                'command_not_found',
                'ignored',
                'unauthorized',
                'unsupported',
                'empty_message',
                'voice_conversion_error',
                'audio_conversion_error'
            ]);
 
            if ($isNormalResponse) {
                // Send fallback message to user for command_not_found
                if ($result['type'] === 'command_not_found') {
                    $fallbackMessage = $this->createCommandNotFoundFallbackMessage($result);
                    $this->sendFriendlyErrorMessage($payload, $fallbackMessage);
                }
 
                // Use appropriate resource method based on status
                if (isset($result['status']) && $result['status'] === 'ignored') {
                    return TelegramWebhookResource::ignored($result['message'] ?? 'Message ignored', $result)
                        ->response()
                        ->setStatusCode(200);
                }
 
                return TelegramWebhookResource::success($result['message'] ?? 'Message processed', $result)
                    ->response()
                    ->setStatusCode(200);
            }
 
            // Check if the message was processed successfully
            if ($result['success']) {
                return TelegramWebhookResource::success($result['message'] ?? 'Message processed successfully', $result)
                    ->response()
                    ->setStatusCode(200);
            }
 
            // Handle actual errors (return 500)
            $this->loggingService->logTelegramEvent('telegram_webhook_processing_failed', [
                'error' => 'Message processing failed',
                'error_message' => $result['message'] ?? 'Unknown error',
                'result' => $result,
                'payload' => $payload,
                'telegram_update_id' => $request->input('update_id'),
                'timestamp' => now()->toISOString()
            ], 'error');
 
            // Send friendly error message to user
            $this->sendFriendlyErrorMessage($payload, $result['message'] ?? 'Desculpe, ocorreu um erro ao processar sua mensagem. Tente novamente.');
 
            return TelegramWebhookResource::error($result['message'] ?? 'Message processing failed', $result)
                ->response()
                ->setStatusCode(500);
 
        } catch (\Exception $e) {
            $duration = (microtime(true) - $startTime) * 1000;
 
            $this->loggingService->logException($e, [
                'operation' => 'telegram_webhook_processing',
                'chat_id' => $request->input('message.chat.id'),
                'user_id' => $request->input('message.from.id'),
                'processing_time_ms' => round($duration, 2)
            ]);
 
            // Send friendly error message to user even for exceptions
            $this->sendFriendlyErrorMessage($request->all(), 'Desculpe, ocorreu um erro inesperado. Nossa equipe foi notificada.');
 
            return TelegramWebhookResource::error('Internal server error')
                ->response()
                ->setStatusCode(500);
        }
    }
 
    /**
     * Set webhook URL for Telegram bot
     */
    public function setWebhook(TelegramWebhookSetupRequest $request): JsonResponse
    {
        try {
            $webhookUrl = $request->validated()['webhook_url'];
            $result = $this->webhookService->setWebhook($webhookUrl);
 
            if (!$result['success']) {
                return TelegramWebhookResource::error($result['message'], $result)
                    ->response()
                    ->setStatusCode(400);
            }
 
            return TelegramWebhookResource::success($result['message'], $result)
                ->response()
                ->setStatusCode(200);
 
        } catch (\Exception $e) {
            $this->loggingService->logException($e, [
                'operation' => 'telegram_webhook_setup',
                'webhook_url' => $request->validated()['webhook_url'] ?? 'unknown'
            ]);
 
            return TelegramWebhookResource::error('Internal server error')
                ->response()
                ->setStatusCode(500);
        }
    }
 
    /**
     * Get webhook info
     */
    public function getWebhookInfo(): JsonResponse
    {
        try {
            $this->loggingService->logTelegramEvent('telegram_webhook_info_request', [
                'action' => 'get_webhook_info'
            ], 'info');
 
            $result = $this->webhookService->getWebhookInfo();
 
            if (!$result['success']) {
                $this->loggingService->logTelegramEvent('telegram_webhook_info_failed', [
                    'error' => $result['message'],
                    'result' => $result
                ], 'error');
 
                return TelegramWebhookResource::error($result['message'], $result)
                    ->response()
                    ->setStatusCode(400);
            }
 
            return TelegramWebhookResource::success('Webhook info retrieved', $result)
                ->response()
                ->setStatusCode(200);
 
        } catch (\Exception $e) {
            $this->loggingService->logException($e, [
                'operation' => 'telegram_webhook_info'
            ]);
 
            return TelegramWebhookResource::error('Internal server error')
                ->response()
                ->setStatusCode(500);
        }
    }
 
    /**
     * Delete webhook
     */
    public function deleteWebhook(): JsonResponse
    {
        try {
            $this->loggingService->logTelegramEvent('telegram_webhook_deletion', [
                'action' => 'delete_webhook'
            ], 'info');
 
            $result = $this->webhookService->deleteWebhook();
 
            if (!$result['success']) {
                $this->loggingService->logTelegramEvent('telegram_webhook_deletion_failed', [
                    'error' => $result['message'],
                    'result' => $result
                ], 'error');
 
                return TelegramWebhookResource::error($result['message'], $result)
                    ->response()
                    ->setStatusCode(400);
            }
 
            $this->loggingService->logTelegramEvent('telegram_webhook_deletion_success', [
                'result' => $result
            ], 'success');
 
            return TelegramWebhookResource::success($result['message'], $result)
                ->response()
                ->setStatusCode(200);
 
        } catch (\Exception $e) {
            $this->loggingService->logException($e, [
                'operation' => 'telegram_webhook_deletion'
            ]);
 
            return TelegramWebhookResource::error('Internal server error')
                ->response()
                ->setStatusCode(500);
        }
    }
 
    /**
     * Test bot functionality
     */
    public function test(): JsonResponse
    {
        try {
            $this->loggingService->logTelegramEvent('telegram_bot_test', [
                'action' => 'test_bot'
            ], 'info');
 
            $result = $this->webhookService->testBot();
 
            if (!$result['success']) {
                $this->loggingService->logTelegramEvent('telegram_bot_test_failed', [
                    'error' => $result['message'],
                    'result' => $result
                ], 'error');
 
                return TelegramWebhookResource::error($result['message'], $result)
                    ->response()
                    ->setStatusCode(400);
            }
 
            $this->loggingService->logTelegramEvent('telegram_bot_test_success', [
                'result' => $result
            ], 'success');
 
            return TelegramWebhookResource::success($result['message'], $result)
                ->response()
                ->setStatusCode(200);
 
        } catch (\Exception $e) {
            $this->loggingService->logException($e, [
                'operation' => 'telegram_bot_test'
            ]);
 
            return TelegramWebhookResource::error('Test failed: ' . $e->getMessage())
                ->response()
                ->setStatusCode(500);
        }
    }
 
    // ... (métodos auxiliares privados serão adicionados na próxima seção)
}

<?php
 
namespace App\Http\Controllers\Api;
 
use App\Http\Controllers\Controller;
use App\Http\Resources\TelegramWebhookResource;
use App\Services\TelegramLoggingService;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
 
class TelegramStatsController extends Controller
{
    public function __construct(
        private TelegramLoggingService $loggingService
    ) {}
 
    /**
     * Get webhook statistics
     */
    public function getStats(): JsonResponse
    {
        try {
            $stats = $this->loggingService->getWebhookStats();
 
            return TelegramWebhookResource::success('Statistics retrieved successfully', [
                'statistics' => $stats
            ])
            ->response()
            ->setStatusCode(200);
 
        } catch (\Exception $e) {
            return TelegramWebhookResource::error('Failed to retrieve statistics: ' . $e->getMessage())
                ->response()
                ->setStatusCode(500);
        }
    }
 
    /**
     * Get recent webhook logs
     */
    public function getRecentLogs(Request $request): JsonResponse
    {
        try {
            $limit = $request->get('limit', 50);
            $limit = min(max((int) $limit, 1), 100); // Limit between 1 and 100
 
            $logs = $this->loggingService->getRecentLogs($limit);
 
            return TelegramWebhookResource::success('Recent logs retrieved successfully', [
                'logs' => $logs,
                'count' => count($logs),
                'limit' => $limit
            ])
            ->response()
            ->setStatusCode(200);
 
        } catch (\Exception $e) {
            return TelegramWebhookResource::error('Failed to retrieve logs: ' . $e->getMessage())
                ->response()
                ->setStatusCode(500);
        }
    }
 
    /**
     * Get webhook health status
     */
    public function getHealthStatus(): JsonResponse
    {
        try {
            $stats = $this->loggingService->getWebhookStats();
 
            // Calculate health metrics
            $totalRequests = $stats['total_requests'] ?? 0;
            $successfulRequests = $stats['successful_requests'] ?? 0;
            $failedRequests = $stats['failed_requests'] ?? 0;
 
            $successRate = $totalRequests > 0 ? ($successfulRequests / $totalRequests) * 100 : 0;
            $errorRate = $totalRequests > 0 ? ($failedRequests / $totalRequests) * 100 : 0;
 
            $healthStatus = [
                'status' => $successRate >= 90 ? 'healthy' : ($successRate >= 70 ? 'warning' : 'critical'),
                'success_rate' => round($successRate, 2),
                'error_rate' => round($errorRate, 2),
                'total_requests' => $totalRequests,
                'successful_requests' => $successfulRequests,
                'failed_requests' => $failedRequests,
                'ignored_requests' => $stats['ignored_requests'] ?? 0,
                'message_requests' => $stats['message_requests'] ?? 0,
                'callback_requests' => $stats['callback_requests'] ?? 0,
                'last_updated' => now()->toISOString(),
            ];
 
            return TelegramWebhookResource::success('Health status retrieved successfully', [
                'health' => $healthStatus
            ])
            ->response()
            ->setStatusCode(200);
 
        } catch (\Exception $e) {
            return TelegramWebhookResource::error('Failed to retrieve health status: ' . $e->getMessage())
                ->response()
                ->setStatusCode(500);
        }
    }
}