PHPackages                             amirkateb/laravel-telegram-hub - 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. [HTTP & Networking](/categories/http)
4. /
5. amirkateb/laravel-telegram-hub

ActiveLibrary[HTTP & Networking](/categories/http)

amirkateb/laravel-telegram-hub
==============================

Laravel Telegram Hub for multi-bot messaging, webhooks, proxy, and logging.

v1.0.2(7mo ago)16MITPHPPHP ^8.2

Since Oct 6Pushed 7mo agoCompare

[ Source](https://github.com/amirkateb/laravel-telegram-hub)[ Packagist](https://packagist.org/packages/amirkateb/laravel-telegram-hub)[ RSS](/packages/amirkateb-laravel-telegram-hub/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (3)Dependencies (2)Versions (4)Used By (0)

📦 Laravel Telegram Hub
======================

[](#-laravel-telegram-hub)

سازنده: **@amirkateb**
نسخه: 1.0

---

فهرست مطالب
-----------

[](#فهرست-مطالب)

- [معرفی](#-%D9%85%D8%B9%D8%B1%D9%81%DB%8C)
- [پیش‌نیازها](#-%D9%BE%DB%8C%D8%B4%D9%86%DB%8C%D8%A7%D8%B2%D9%87%D8%A7)
- [نصب](#-%D9%86%D8%B5%D8%A8)
- [پیکربندی](#-%D9%BE%DB%8C%DA%A9%D8%B1%D8%A8%D9%86%D8%AF%DB%8C)
- [ساختار فایل‌ها (مانیفست)](#-%D8%B3%D8%A7%D8%AE%D8%AA%D8%A7%D8%B1-%D9%81%D8%A7%DB%8C%D9%84%D9%87%D8%A7-%D9%85%D8%A7%D9%86%DB%8C%D9%81%D8%B3%D8%AA)
- [دیتابیس](#-%D8%AF%DB%8C%D8%AA%D8%A7%D8%A8%DB%8C%D8%B3)
- [مسیرهای HTTP (Routes)](#-%D9%85%D8%B3%DB%8C%D8%B1%D9%87%D8%A7%DB%8C-http-routes)
- [امنیت وبهوک](#-%D8%A7%D9%85%D9%86%DB%8C%D8%AA-%D9%88%D8%A8%D9%87%D9%88%DA%A9)
- [مدیریت وبهوک (CLI / API / Service)](#-%D9%85%D8%AF%DB%8C%D8%B1%DB%8C%D8%AA-%D9%88%D8%A8%D9%87%D9%88%DA%A9-cli--api--service)
- [دریافت پیام و اتصال منطق پروژه](#-%D8%AF%D8%B1%DB%8C%D8%A7%D9%81%D8%AA-%D9%BE%DB%8C%D8%A7%D9%85-%D9%88-%D8%A7%D8%AA%D8%B5%D8%A7%D9%84-%D9%85%D9%86%D8%B7%D9%82-%D9%BE%D8%B1%D9%88%DA%98%D9%87)
- [ارسال پیام‌ها (همه انواع رایج)](#-%D8%A7%D8%B1%D8%B3%D8%A7%D9%84-%D9%BE%DB%8C%D8%A7%D9%85%D9%87%D8%A7-%D9%87%D9%85%D9%87-%D8%A7%D9%86%D9%88%D8%A7%D8%B9-%D8%B1%D8%A7%DB%8C%D8%AC)
- [سرویس‌های تفکیک‌شده (Apis)](#-%D8%B3%D8%B1%D9%88%DB%8C%D8%B3%D9%87%D8%A7%DB%8C-%D8%AA%D9%81%DA%A9%DB%8C%DA%A9%D8%B4%D8%AF%D9%87-apis)
- [لاگ‌ها](#-%D9%84%D8%A7%DA%AF%D9%87%D8%A7)
- [عیب‌یابی و نکات عملیاتی](#-%D8%B9%DB%8C%D8%A8%DB%8C%D8%A7%D8%A8%DB%8C-%D9%88-%D9%86%DA%A9%D8%A7%D8%AA-%D8%B9%D9%85%D9%84%DB%8C%D8%A7%D8%AA%DB%8C)
- [نقشه راه پیشنهادی (Optional)](#-%D9%86%D9%82%D8%B4%D9%87-%D8%B1%D8%A7%D9%87-%D9%BE%DB%8C%D8%B4%D9%86%D9%87%D8%A7%D8%AF%DB%8C-optional)
- [پشتیبانی، مجوز](#-%D9%BE%D8%B4%D8%AA%DB%8C%D8%A8%D8%A7%D9%86%DB%8C-%D9%85%D8%AC%D9%88%D8%B2)

---

🧠 معرفی
-------

[](#-معرفی)

**Laravel Telegram Hub** یک پکیج جامع برای ادغام کامل با **Telegram Bot API** در Laravel است. تمرکز پکیج بر **Multi-Bot واقعی**، **وبهوک امن**، **آپلود مدیا از دیسک (multipart)**، **مدیریت از دیتابیس** و **لاگ‌گیری کامل** است.

ویژگی‌ها:

- ست/حذف/استعلام وبهوک با Secret Token
- ارسال انواع پیام: متن، عکس، ویدیو، سند، ویس/آدیو، انیمیشن، ویدئونوت، گروه مدیا، لوکیشن، … + ویرایش/حذف
- آپلود مستقیم فایل از دیسک با `Support\InputFile`
- مدیریت بات‌ها از **config** یا **دیتابیس** (جدول `telegram_bots`)
- لاگ کامل inbound/outbound در جدول `telegram_logs`
- CLI Commands و API Endpoints برای مدیریت
- تنظیم Proxy و Timeout‌ها

---

✅ پیش‌نیازها
------------

[](#-پیش‌نیازها)

- PHP 8.2+
- Laravel 10 یا 11
- ext-curl, ext-json
- HTTPS برای وبهوک

---

🚀 نصب
-----

[](#-نصب)

```
composer require amirkateb/laravel-telegram-hub
php artisan vendor:publish --provider="Amirkateb\TelegramHub\TelegramHubServiceProvider" --tag=config
php artisan vendor:publish --provider="Amirkateb\TelegramHub\TelegramHubServiceProvider" --tag=migrations
php artisan migrate
```

---

⚙️ پیکربندی
-----------

[](#️-پیکربندی)

### .env

[](#env)

```
TELEGRAM_DEFAULT_BOT=default
TELEGRAM_BOT_TOKEN=123456:ABC
TELEGRAM_WEBHOOK_SECRET=your-long-secret
TELEGRAM_HUB_ROUTE_PREFIX=telegram-hub
TELEGRAM_HUB_ROUTE_MIDDLEWARE=api
TELEGRAM_PROXY_ENABLED=false
TELEGRAM_PROXY_HTTP=
TELEGRAM_PROXY_HTTPS=
TELEGRAM_HTTP_TIMEOUT=15
TELEGRAM_HTTP_CONNECT_TIMEOUT=10
TELEGRAM_HUB_LOG_CHANNEL=stack
TELEGRAM_WEBHOOK_BASE_URL=https://your-domain.com
```

### config/telegram\_hub.php (گزیده)

[](#configtelegram_hubphp-گزیده)

```
return [
    'default_bot' => env('TELEGRAM_DEFAULT_BOT', 'default'),

    'bots' => [
        'default' => env('TELEGRAM_BOT_TOKEN'),
        // 'sales' => env('TELEGRAM_BOT_TOKEN_SALES'),
    ],

    'proxy' => [
        'enabled' => (bool) env('TELEGRAM_PROXY_ENABLED', false),
        'http' => env('TELEGRAM_PROXY_HTTP'),
        'https' => env('TELEGRAM_PROXY_HTTPS'),
    ],

    'request' => [
        'timeout' => (int) env('TELEGRAM_HTTP_TIMEOUT', 15),
        'connect_timeout' => (int) env('TELEGRAM_HTTP_CONNECT_TIMEOUT', 10),
    ],

    'webhook' => [
        'base_url' => env('TELEGRAM_WEBHOOK_BASE_URL'),
        'secret_token' => env('TELEGRAM_WEBHOOK_SECRET'),
    ],

    'routes' => [
        'prefix' => env('TELEGRAM_HUB_ROUTE_PREFIX', 'telegram-hub'),
        'middleware' => array_filter(array_map('trim', explode(',', (string) env('TELEGRAM_HUB_ROUTE_MIDDLEWARE', 'api')))),
    ],

    'log_channel' => env('TELEGRAM_HUB_LOG_CHANNEL', 'stack'),
];
```

---

🗂️ ساختار فایل‌ها (مانیفست)
---------------------------

[](#️-ساختار-فایل‌ها-مانیفست)

```
amirkateb/laravel-telegram-hub
├─ config/telegram_hub.php
├─ routes/telegram_hub.php
├─ src/
│  ├─ TelegramHubServiceProvider.php
│  ├─ Http/Controllers/
│  │  ├─ WebhookController.php
│  │  └─ WebhookSetupController.php
│  ├─ Services/
│  │  └─ BotManager.php
│  ├─ Console/Commands/
│  │  ├─ TelegramHubSetWebhook.php
│  │  ├─ TelegramHubDeleteWebhook.php
│  │  ├─ TelegramHubWebhookInfo.php
│  │  ├─ TelegramHubSend.php
│  │  ├─ TelegramHubSendTest.php
│  │  ├─ TelegramHubBotUpsert.php
│  │  ├─ TelegramHubBotDeleteWebhook.php
│  │  └─ TelegramHubBotInfo.php
│  ├─ Apis/
│  │  ├─ MessageApi.php
│  │  ├─ MediaApi.php
│  │  └─ ChatAdminApi.php
│  └─ Support/
│     ├─ Http.php
│     └─ InputFile.php
└─ database/migrations/
   ├─ xxxx_xx_xx_xxxxxx_create_telegram_bots_table.php
   └─ xxxx_xx_xx_xxxxxx_create_telegram_logs_table.php

```

---

🧩 دیتابیس
---------

[](#-دیتابیس)

### جدول `telegram_bots`

[](#جدول-telegram_bots)

ستونتوضیحkeyکلید یکتای بات (مثال: sales)nameنام نمایشیtokenتوکن BotFatherwebhook\_urlآدرس وبهوک فعلیsecret\_tokenتوکن امنیتی وبهوکenabledفعال/غیرفعالallowed\_updatesJSON از نوع آپدیت‌های مجازtimestampsزمان‌هانمونه درج:

```
DB::table('telegram_bots')->insert([
  'key' => 'sales',
  'name' => 'ربات فروش',
  'token' => '123456789:ABC_DEF',
  'webhook_url' => 'https://your-domain.com/telegram-hub/webhook/sales',
  'secret_token' => 'sales-secret',
  'enabled' => true,
  'allowed_updates' => json_encode(['message','callback_query']),
  'created_at' => now(),
  'updated_at' => now(),
]);
```

### جدول `telegram_logs`

[](#جدول-telegram_logs)

برای ثبت inbound/outbound با فیلدهای: `direction, bot_key, bot_id, chat_id, message_id, method, status_code, ok, error_code, error_description, payload, response, timestamps`

---

🔗 مسیرهای HTTP (Routes)
-----------------------

[](#-مسیرهای-http-routes)

متدمسیرتوضیحPOST`/{prefix}/webhook/{bot}`دریافت آپدیت‌های بات مشخصPOST`/{prefix}/webhook`دریافت آپدیت‌های بات پیش‌فرضPOST`/{prefix}/set-webhook/{bot}`ست وبهوک + امکان ذخیره از طریق BotManager در DBDELETE`/{prefix}/delete-webhook/{bot}`حذف وبهوک + به‌روزرسانی DBGET`/{prefix}/webhook-info/{bot}`دریافت وضعیت وبهوک> مقادیر `prefix` و `middleware` از کانفیگ خوانده می‌شود.
> امنیت: بررسی `X-Telegram-Bot-Api-Secret-Token` در `WebhookController` انجام می‌شود (از DB یا config).

---

🛡️ امنیت وبهوک
--------------

[](#️-امنیت-وبهوک)

- `TELEGRAM_WEBHOOK_SECRET` را تنظیم و هنگام `setWebhook` ارسال کنید.
- وبهوک فقط از HTTPS خوانده شود.
- برای روت‌های مدیریتی (set/delete/info) می‌توانید Middleware احراز هویت اضافه کنید.
- امکان غیرفعال‌سازی بات از طریق فیلد `enabled` در DB وجود دارد.

---

📡 مدیریت وبهوک (CLI / API / Service)
------------------------------------

[](#-مدیریت-وبهوک-cli--api--service)

### 1) CLI ساده (بدون Persist)

[](#1-cli-ساده-بدون-persist)

```
php artisan telegram-hub:webhook:set --url="https://your-domain.com/telegram-hub/webhook/default" --bot=default --secret="$TELEGRAM_WEBHOOK_SECRET" --allowed-updates=message,callback_query
php artisan telegram-hub:webhook:info --bot=default
php artisan telegram-hub:webhook:delete --bot=default
```

### 2) BotManager (ست و ذخیره در DB)

[](#2-botmanager-ست-و-ذخیره-در-db)

```
use Amirkateb\TelegramHub\Services\BotManager;

$res = app(BotManager::class)->setWebhookAndPersist(
  'sales',
  '123456789:ABC_DEF',
  'ربات فروش',
  null,
  'sales-secret',
  ['message','callback_query'],
  true
);
```

### 3) CLI با Persist

[](#3-cli-با-persist)

```
php artisan telegram-hub:bot:upsert --key=sales --token=123456789:ABC_DEF --name="ربات فروش" --secret="sales-secret" --allowed-updates=message,callback_query --enabled=1
php artisan telegram-hub:bot:info --key=sales
php artisan telegram-hub:bot:delete-webhook --key=sales
```

### 4) API داخلی

[](#4-api-داخلی)

```
POST   /{prefix}/set-webhook/{bot}      (body: { token?, name?, url?, secret?, allowed_updates?, enabled? })
DELETE /{prefix}/delete-webhook/{bot}
GET    /{prefix}/webhook-info/{bot}
```

---

💬 دریافت پیام و اتصال منطق پروژه
--------------------------------

[](#-دریافت-پیام-و-اتصال-منطق-پروژه)

### روش توصیه‌شده: Middleware روی روت وبهوک پکیج

[](#روش-توصیه‌شده-middleware-روی-روت-وبهوک-پکیج)

1. بسازید: `app/Http/Middleware/TelegramHubInbound.php`

```