Документация / v2

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

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

Сервис

Проверяем...

Версия API

Загрузка...

Хранилище

SQLite + WAL

Один callback достаточно передать один разHub сохранит маршрут и перед каждой следующей отправкой проверит Telegram webhook через getWebhookInfo.

01 / requestВаше приложениеПередаёт сообщение и callback URL в Hub.

02 / routingTelegram HubПроверяет маршрут, отправляет и журналирует.

03 / deliveryTelegram APIВозвращает update через webhook нужного бота.

Начало работы

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

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

curl -X POST "$HUB_URL/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',
]);

Hub определит бота

bot_token имеет приоритет над именем channel.

Создаст маршрут в SQLite

Callback URL, HMAC secret и закрытый входящий путь сохраняются между перезапусками.

Подключит Telegram webhook

Для этого публичный адрес Hub должен начинаться с https://.

Отправит сообщение

Ответ содержит результат Telegram и служебный блок callback.

Маршрутизация

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

Маршрут связывается с bot token. Callback можно передавать в каждом запросе или только при первой настройке.

Поле	Назначение	Хранение
`callback_url`	Endpoint приложения для Telegram update	SQLite
`callback_secret`	Ключ подписи `X-Hub-Signature`	SQLite
`callback_delivery_mode`	`sync` или надёжная очередь `durable`	SQLite
`webhook_url`	Закрытый входящий URL конкретного бота в Hub	SQLite
`telegram_secret`	Проверка запроса от Telegram	SQLite

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

Загрузка сохранённого маршрута

Если callback не передан, Hub ищет его по bot_token или channel.

Сверка с Telegram

getWebhookInfo должен вернуть внутренний webhook URL текущего Hub.

Самовосстановление

При пустом или чужом URL Hub повторяет setWebhook с сохранённым secret.

Фиксация результата

В SQLite и панели сохраняются ok, registered, repaired или failed.

Telegram не возвращает secret tokenУдалённо проверяется URL. При восстановлении Hub повторно передаёт ранее сохранённый telegram_secret.

Безопасность

Авторизация

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

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

Поверхность	Защита
`/send`, `/telegram/*`, `/channels`	Bearer API key или X-API-Key
`/admin`, `/admin/api/*`	Admin session или HTTP Basic
`/webhooks/telegram/*`	X-Telegram-Bot-Api-Secret-Token
`/health`, `/docs`, `/openapi.json`	Публично

Входящий поток

Доставка Telegram update

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

Режим	Ответ Telegram	Повтор
`sync`	`200` после ответа callback `2xx`	Telegram повторяет update после ошибки Hub
`durable`	`200` после записи в SQLite	Воркеры Hub, exponential backoff и статус `dead`

Заголовок	Значение
`X-Hub-Bot`	Стабильное имя маршрута
`X-Hub-Event-Id`	ID события в SQLite и панели
`X-Telegram-Update-Id`	Исходный update ID, если он присутствует
`X-Hub-Signature`	`sha256=<HMAC>` от точного тела запроса

At least once в durable-режимеПолучатель должен дедуплицировать запросы по X-Hub-Event-Id. Состояния queued, retrying, forwarding и dead видны в панели.

OpenAPI reference

HTTP API

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

По этому запросу endpoints не найдены.

Диагностика

Коды ошибок

Код	Когда возвращается
401	API key отсутствует или неверен
403	Не совпал Telegram webhook secret
404	Маршрут, событие или admin-объект не найден
409	Конфликт имени, token или состояния retry
422	Некорректные поля, неизвестный channel или нет HTTPS URL
502	Ошибка Telegram API либо callback-получателя
503	Сервис или административная авторизация не готовы

Каждый ответ содержит 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

Production

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

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

Перед запускомНаправьте DNS-запись домена на сервер и откройте TCP 80, TCP/UDP 443. Активный Nginx определяется автоматически; для полностью ручного proxy используйте -x.