Документация BotGate API

BotGate — прокси-сервис для Telegram Bot API. Он позволяет отправлять запросы к Telegram через единый шлюз с авторизацией по API-ключу, логированием и поддержкой webhook.

Быстрый старт Создать аккаунт

Быстрый старт

Зарегистрируйтесь и войдите в личный кабинет.
Добавьте бота: нажмите «Добавить бота», введите имя и токен от @BotFather.
Скопируйте ваш API-ключ вида bg_live_... со страницы дашборда.
Используйте URL прокси вместо стандартного api.telegram.org.

Аутентификация

Все запросы к Proxy API должны содержать заголовок Authorization с API-ключом пользователя в формате Bearer.

HTTP заголовок

Authorization: Bearer bg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

⚠️ Храните API-ключ в секрете. В случае компрометации пересоздайте его в личном кабинете.

Прокси Telegram Bot API

Формат запроса

URL

https://bot-gate.ru/api/v1/bots/{botPublicId}/telegram/{method}

{botPublicId} — идентификатор бота вида bot_xxxxxxxxxxxx, отображается в карточке бота.
{method} — любой метод Telegram Bot API, например sendMessage.
Метод getUpdates заблокирован — используйте webhook.

Пример: отправка сообщения

curl

curl -X POST https://bot-gate.ru/api/v1/bots/bot_xxxxxxxxxxxx/telegram/sendMessage \
  -H "Authorization: Bearer bg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": 123456789,
    "text": "Привет от BotGate!",
    "parse_mode": "HTML"
  }'

Пример: отправка фото

curl (multipart)

curl -X POST https://bot-gate.ru/api/v1/bots/bot_xxxxxxxxxxxx/telegram/sendPhoto \
  -H "Authorization: Bearer bg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -F "chat_id=123456789" \
  -F "photo=@/path/to/photo.jpg" \
  -F "caption=Подпись к фото"

Пример ответа

JSON

{
  "ok": true,
  "result": {
    "message_id": 42,
    "from": { "id": 987654321, "is_bot": true, "first_name": "MyBot", "username": "my_bot" },
    "chat": { "id": 123456789, "type": "private" },
    "date": 1700000000,
    "text": "Привет от BotGate!"
  }
}

Rate Limiting

Каждый API-ключ ограничен 600 запросами в минуту, каждый отдельный бот — 300 запросами в минуту. При превышении возвращается HTTP 429.

Webhook

BotGate может принимать обновления от Telegram и доставлять их на ваш сервер. Для этого укажите Webhook URL в настройках бота.

Как это работает

Telegram отправляет обновление на BotGate.
BotGate сохраняет событие и помещает задачу в очередь.
BotGate делает POST запрос на ваш Webhook URL.
При неудаче — до 3 попыток с задержками 0, 60 и 300 секунд.

Заголовки входящего запроса

HTTP Headers

Content-Type: application/json
User-Agent: BotGate Webhook
X-BotGate-Bot-Id: bot_xxxxxxxxxxxx
X-BotGate-Event-Id: 42
X-BotGate-Signature: sha256_hmac_hex_signature

Проверка подписи

Заголовок X-BotGate-Signature — это HMAC-SHA256 от тела запроса, подписанный секретом вашего бота (webhook_secret). Секрет отображается в карточке бота.

PHP — проверка подписи

$payload  = file_get_contents('php://input');
$secret   = 'ваш_webhook_secret';
$expected = hash_hmac('sha256', $payload, $secret);
$received = $_SERVER['HTTP_X_BOTGATE_SIGNATURE'] ?? '';

if (!hash_equals($expected, $received)) {
    http_response_code(403);
    exit('Invalid signature');
}

$update = json_decode($payload, true);
// обрабатываем $update...

Пример payload

JSON

{
  "update_id": 100500,
  "message": {
    "message_id": 1,
    "from": { "id": 123456789, "first_name": "Ivan", "username": "ivan" },
    "chat": { "id": 123456789, "type": "private" },
    "date": 1700000000,
    "text": "/start"
  }
}

💡 Ваш сервер должен ответить любым HTTP 2xx в течение 10 секунд, иначе доставка считается неудачной.

Коды ошибок

HTTP код	Причина	Решение
`401`	Отсутствует или неверный API-ключ	Проверьте заголовок `Authorization: Bearer ...`
`403`	Бот отключён или метод запрещён	Включите бота в кабинете; не используйте `getUpdates`
`404`	Бот не найден	Проверьте `botPublicId` в URL
`429`	Превышен rate limit	Снизьте частоту запросов (макс. 600/мин)
`502`	Telegram недоступен	Повторите запрос через несколько секунд