Интеграция с Telegram через один управляемый Hub

Отправляйте сообщения от нескольких ботов, принимайте Telegram update через единый публичный адрес и пересылайте их в нужные приложения с журналом в SQLite.

Первая двусторонняя отправка

Нужны API key Hub, токен Telegram-бота и HTTPS endpoint вашего приложения, принимающий JSON.

curl -X POST "https://hub.vitmp.ru/send" \
  -H "Authorization: Bearer $HUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bot_token": "123456:ABC...",
    "chat_id": "123456789",
    "text": "Новая заявка",
    "parse_mode": "HTML",
    "callback_url": "https://app.example.com/hooks/telegram",
    "callback_secret": "shared-hmac-secret",
    "callback_delivery_mode": "durable"
  }'

$hub = new HubTelegramClient([
    'url' => env('TELEGRAM_HUB_URL'),
    'api_key' => env('TELEGRAM_HUB_API_KEY'),
    'callback_url' => route('hooks.telegram'),
    'callback_secret' => env('TELEGRAM_HUB_CALLBACK_SECRET'),
]);

$hub->send($chatId, 'Новая заявка', [
    'parse_mode' => 'HTML',
]);

Автоматические обратные webhook

Маршрут связывается с bot token. Callback можно передать отдельным полем или привычным вызовом setWebhook; Telegram в обоих случаях получает только уникальный адрес Hub.

Если приложение вызывает setWebhook

Передайте вызов в POST /telegram/call. Значение params.url останется конечным адресом приложения, но в Telegram Hub зарегистрирует собственный уникальный URL.

{
  "bot_token": "123456:ABC...",
  "method": "setWebhook",
  "params": {
    "url": "https://app.example.com/hooks/telegram",
    "allowed_updates": ["message", "callback_query"]
  },
  "callback_secret": "shared-hmac-secret",
  "callback_delivery_mode": "durable"
}

Проверка перед каждой отправкой

Авторизация

Исходящий API принимает Bearer token или X-API-Key. Панель и admin API используют отдельные логин и пароль.

Authorization: Bearer <HUB_API_KEY>
# либо
X-API-Key: <HUB_API_KEY>

Доставка Telegram update

Hub загружает маршрут из SQLite, сохраняет исходный payload и доставляет точный JSON в совместимом синхронном режиме либо через надёжную очередь.

Исходящие запросы в Telegram

Каждый вызов отправки сначала сохраняется в outbound_jobs, а завершённые попытки — в outbound_attempts. Успешный JSON остаётся совместимым, а заголовок X-Hub-Outbound-Job-Id содержит ID операции. Timeout, Telegram 429 и 5xx повторяются фоновыми воркерами; состояние и история возвращаются через GET /outbound/{id}. В журнале администратора доступны диагноз, сырой ответ и ручной повтор неуспешной операции.

HTTP API

Справочник ниже формируется из текущей схемы запущенного Hub. Для ручных запросов доступен Swagger UI, исходная схема — в OpenAPI JSON.

Коды ошибок

Каждый ответ содержит X-Request-ID. Используйте его для поиска связанной записи в журнале сервиса.

CLI управления

Глобальная команда hub работает из любого каталога. Запустите hub -h, hub bot -h или hub event -h для подробной справки. Старый hubctl.sh остаётся совместимым.

sudo hub creds
sudo hub doctor
sudo hub bot list
sudo hub bot add orders \
  --token '123456:ABC...' \
  --callback-url 'https://app.example.com/hooks/telegram' \
  --secret 'shared-secret' \
  --delivery-mode durable \
  --register
sudo hub event list --limit 20
sudo hub backup

Мониторинг, дамп и SDK

/ready проверяет SQLite и оба пула воркеров, а /metrics отдаёт Prometheus-метрики без payload и секретов.

Полные alert rules находятся в MONITORING.md. В разделе «Система» администратор может скачать согласованный дамп SQLite, созданный Online Backup API.

Официальные клиенты

# Python
python -m pip install ./sdk/python

# TypeScript
cd sdk/typescript && pnpm install && pnpm run build

Оба SDK поддерживают отправку, callback-настройки, readiness и чтение состояния исходящей операции. Подробности: SDK.md.

Развёртывание на домене

Telegram принимает webhook только по публичному HTTPS. Установщик автоматически использует активный Nginx и Certbot либо запускает Caddy, не затрагивая другие сайты.

curl -fsSL https://gitlab.com/valvic/hub/-/raw/main/install.sh \
  | sudo bash -s -- -d hub.example.com

# Обновление
curl -fsSL https://gitlab.com/valvic/hub/-/raw/main/install.sh \
  | sudo bash -s -- -u