PHPackages 3neti/messaging-bot - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. 3neti/messaging-bot ActiveLibrary[Utility & Helpers](/categories/utility) 3neti/messaging-bot =================== Multi-channel messaging bot for PayCode voucher operations (Telegram, WhatsApp, Viber) 1.0.1(4mo ago)01proprietaryPHPPHP ^8.2 Since Apr 3Pushed 4mo agoCompare [ Source](https://github.com/3neti/messaging-bot)[ Packagist](https://packagist.org/packages/3neti/messaging-bot)[ RSS](/packages/3neti-messaging-bot/feed)WikiDiscussions main Synced 1w ago READMEChangelogDependencies (9)Versions (3)Used By (0) Messaging Bot Package ===================== [](#messaging-bot-package) Multi-channel messaging bot for PayCode voucher operations. Currently supports Telegram, with WhatsApp and Viber planned for future phases. Features -------- [](#features) - **Multi-step conversation flows** - Stateful conversations for complex operations - **Platform-agnostic core** - Normalized DTOs work across all messaging platforms - **Pluggable drivers** - Easy to add new messaging platforms - **Admin authorization** - Restrict commands to configured admin chat IDs - **Laravel Cache integration** - Conversation state persists across messages Installation ------------ [](#installation) The package is included in the mono-repo. Add it to your host app's `composer.json`: ``` { "repositories": [ { "type": "path", "url": "./packages/messaging-bot" } ], "require": { "lbhurtado/messaging-bot": "@dev" } } ``` Then run: ``` composer update lbhurtado/messaging-bot ``` Configuration ------------- [](#configuration) Publish the config file: ``` php artisan vendor:publish --tag=messaging-bot-config ``` ### Environment Variables [](#environment-variables) ``` # Telegram Bot TELEGRAM_BOT_TOKEN=your_bot_token_here TELEGRAM_WEBHOOK_SECRET=your_secret_here TELEGRAM_ADMIN_CHAT_IDS=123456789,987654321 # General MESSAGING_BOT_CONVERSATION_TTL=1800 ``` Setting Up Telegram ------------------- [](#setting-up-telegram) ### 1. Create a Bot [](#1-create-a-bot) 1. Open Telegram and search for `@BotFather` 2. Send `/newbot` and follow the prompts 3. Copy the bot token to `TELEGRAM_BOT_TOKEN` ### 2. Set Webhook [](#2-set-webhook) Set your webhook URL (replace with your domain): ``` curl -X POST "https://api.telegram.org/bot/setWebhook" \ -H "Content-Type: application/json" \ -d '{"url": "https://yourdomain.com/messaging/telegram/webhook", "secret_token": "your_secret"}' ``` Or use the driver directly: ``` use LBHurtado\MessagingBot\Drivers\Telegram\TelegramDriver; $driver = app(TelegramDriver::class); $driver->setWebhook('https://yourdomain.com/messaging/telegram/webhook'); ``` ### 3. Local Development [](#3-local-development) For local development, use the test command to simulate messages: ``` # Simulate a message php artisan test:messaging "/redeem" # Continue the conversation php artisan test:messaging "VOUCHER-CODE" # Simulate contact sharing (phone number) php artisan test:messaging "" --contact # Test deep link (as if user clicked t.me/bot?start=redeem_CODE) php artisan test:messaging "/start redeem_ABCD" # Use different chat ID (for separate conversation state) php artisan test:messaging "/redeem" --chat-id=99999 # Specify mobile number for contact sharing php artisan test:messaging "" --contact --mobile=09181234567 ``` Alternatively, use long polling for real Telegram interaction: ``` php artisan messaging:poll ``` Available Commands ------------------ [](#available-commands) ### Public Commands [](#public-commands) CommandDescription`/start`Welcome message`/help`Show available commands`/balance`Check wallet balance (requires linked account)`/redeem`Start voucher redemption flow`/cancel`Cancel current operation### Admin Commands [](#admin-commands) CommandDescription`/generate`Generate multiple vouchers`/disburse`Quick single-voucher creationDeep Links ---------- [](#deep-links) Telegram deep links allow users to start redemption with a single click: ``` https://t.me/your_bot?start=redeem_VOUCHER-CODE https://t.me/your_bot?start=disburse_VOUCHER-CODE ``` **Format:** `start=action_param` (underscore separator) **Examples:** ``` https://t.me/xchange_paycode_bot?start=redeem_3LGB-GX8S https://t.me/xchange_paycode_bot?start=disburse_ABCD-1234 ``` When a user clicks a deep link: 1. Telegram opens and starts the bot 2. Bot automatically validates the voucher code 3. User sees amount and is prompted to share phone (or confirm if returning user) Redemption UX Flow ------------------ [](#redemption-ux-flow) ### First-Time User (3 steps) [](#first-time-user-3-steps) ``` Click: t.me/bot?start=redeem_ABCD → ✅ ₱100.00 found! We need your mobile number to send the funds. [📱 Share Phone Number] *taps share* → 📋 You will receive: ₱100.00 → GCash:09173011987 [✅ Accept] [✏️ Change Account] *taps accept* → 🎉 Done! ``` ### Returning User (2 steps) [](#returning-user-2-steps) Phone number is cached for 30 days after successful redemption: ``` Click: t.me/bot?start=redeem_EFGH → ✅ ₱100.00 found! Send to GCash:09173011987? [✅ Accept] [📱 Different Number] *taps accept* → 🎉 Done! ``` Architecture ------------ [](#architecture) ``` ┌─────────────────────────────────────────────────────────┐ │ Drivers (Platform-Specific) │ │ TelegramDriver │ WhatsAppDriver │ ViberDriver │ └────────────────────┬────────────────────────────────────┘ │ ┌────────────────────▼────────────────────────────────────┐ │ Core Engine │ │ MessagingKernel → IntentRouter → Handler/Flow │ │ ConversationStore (Laravel Cache) │ └────────────────────┬────────────────────────────────────┘ │ ┌────────────────────▼────────────────────────────────────┐ │ Domain Actions │ │ GenerateVouchers │ RedeemViaSms │ ProcessRedemption │ └─────────────────────────────────────────────────────────┘ ``` Adding a New Handler -------------------- [](#adding-a-new-handler) Create a handler extending `BaseMessagingHandler`: ``` namespace LBHurtado\MessagingBot\Handlers; use LBHurtado\MessagingBot\Data\NormalizedResponse; use LBHurtado\MessagingBot\Data\NormalizedUpdate; class MyHandler extends BaseMessagingHandler { protected function process(NormalizedUpdate $update): NormalizedResponse { return NormalizedResponse::text('Hello from MyHandler!'); } // Optional: require authentication public function requiresAuth(): bool { return true; } } ``` Register in config: ``` // config/messaging-bot.php 'handlers' => [ 'my_intent' => \LBHurtado\MessagingBot\Handlers\MyHandler::class, ], ``` Adding a New Flow ----------------- [](#adding-a-new-flow) Create a flow extending `BaseFlow`: ``` namespace LBHurtado\MessagingBot\Flows; class MyFlow extends BaseFlow { public function initialStep(): string { return 'step1'; } public function steps(): array { return ['step1', 'step2', 'finalize']; } protected function promptStep1(ConversationState $state): NormalizedResponse { return NormalizedResponse::text('Enter something:'); } protected function handleStep1(NormalizedUpdate $update, ConversationState $state, string $input): array { $newState = $state->with('value', $input)->advanceTo('step2'); return [ 'response' => $this->promptStep2($newState), 'state' => $newState, ]; } // ... more steps } ``` Webhook Endpoints ----------------- [](#webhook-endpoints) PlatformEndpointTelegram`POST /messaging/telegram/webhook`WhatsApp`POST /messaging/whatsapp/webhook` (planned)Viber`POST /messaging/viber/webhook` (planned)Testing ------- [](#testing) ### Unit Tests [](#unit-tests) ``` # Run package tests cd packages/messaging-bot composer test # Or from root php artisan test packages/messaging-bot/tests ``` ### Manual Testing [](#manual-testing) ``` # Test the full redemption flow php artisan cache:clear php artisan test:messaging "/start redeem_VOUCHER-CODE" php artisan test:messaging "" --contact php artisan test:messaging "accept" # Test returning user (with cached phone) php artisan tinker --execute="Cache::put('messaging:phone:12345', '+639173011987', now()->addDays(30));" php artisan test:messaging "/start redeem_ANOTHER-CODE" php artisan test:messaging "accept" ``` License ------- [](#license) Proprietary - All rights reserved. ### Health Score 34 — LowBetter than 74% of packages Maintenance75 Regular maintenance activity Popularity1 Limited adoption so far Community6 Small or concentrated contributor base Maturity48 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~0 days Total 2 Last Release 137d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/586e1ed70140038e6348728222adbcf68bfc4455b1f94a4f8bcbe57917a63d57?d=identicon)[3neti](/maintainers/3neti) --- Top Contributors [![3neti](https://avatars.githubusercontent.com/u/89447696?v=4)](https://github.com/3neti "3neti (2 commits)") ### Code Quality TestsPest ### Embed Badge ![Health badge](/badges/3neti-messaging-bot/health.svg) ``` [![Health](https://phpackages.com/badges/3neti-messaging-bot/health.svg)](https://phpackages.com/packages/3neti-messaging-bot) ``` ### Alternatives [psalm/plugin-laravel Psalm plugin for Laravel 3345.4M354](/packages/psalm-plugin-laravel)[aedart/athenaeum Athenaeum is a mono repository; a collection of various PHP packages 265.2k](/packages/aedart-athenaeum)[roots/acorn Framework for Roots WordPress projects built with Laravel components. 9922.4M146](/packages/roots-acorn)[fleetbase/core-api Core Framework and Resources for Fleetbase API 1239.7k25](/packages/fleetbase-core-api)[api-platform/laravel API Platform support for Laravel 58190.1k21](/packages/api-platform-laravel)[spatie/laravel-export Create a static site bundle from a Laravel app 679153.2k7](/packages/spatie-laravel-export) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)