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

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

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

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

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

Не хотите формировать запросы вручную? Установите готовый SDK для PHP или Laravel.

Официальные SDK

Чтобы не формировать HTTP-запросы вручную, используйте готовые пакеты. Они дают типизированный клиент для вызова методов Bot API, проверку подписи вебхуков и разбор входящих обновлений.

PHP

GitHub

Не зависит от фреймворка. Требуется PHP 8.2+ и PSR-18 HTTP-клиент.

Laravel

GitHub

Интеграция SDK с Laravel 11+: фасад, маршрут вебхука и события.

💡 Полные примеры (установка, вебхуки, загрузка файлов, обработка ошибок) — в README пакетов на GitHub.

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

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

HTTP заголовок

Authorization: Bearer bg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

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

Прокси Telegram Bot API

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

URL

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

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

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

curl

curl -X POST https://bot-gate.ru/api/v1/bots/bot_xxxxxxxxxxxx/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/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.

Скачивание файлов

Telegram не позволяет скачать файл напрямую без токена бота. BotGate проксирует скачивание, чтобы вам не нужно было хранить токен на клиентской стороне.

Шаг 1 — получить file_path

Вызовите метод getFile, передав file_id из любого объекта (фото, документ, голосовое и т.д.). В ответе вернётся file_path.

curl

curl -X POST https://bot-gate.ru/api/v1/bots/bot_xxxxxxxxxxxx/getFile \
  -H "Authorization: Bearer bg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"file_id": "BQACAgIAAxkBAAIBs2..."}'

Ответ

{
  "ok": true,
  "result": {
    "file_id": "BQACAgIAAxkBAAIBs2...",
    "file_size": 14987,
    "file_path": "documents/file_123.pdf"
  }
}

Шаг 2 — скачать файл

Используйте полученный file_path в URL запроса на скачивание. Ответ — бинарный поток файла с корректным Content-Type.

URL

GET https://bot-gate.ru/api/v1/bots/{botPublicId}/files/{file_path}

curl

curl -O -J \
  -H "Authorization: Bearer bg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  "https://bot-gate.ru/api/v1/bots/bot_xxxxxxxxxxxx/files/documents/file_123.pdf"

💡 Файлы в Telegram доступны ограниченное время. Не кешируйте file_path дольше нескольких часов — запрашивайте актуальный через getFile при необходимости.

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 недоступен	Повторите запрос через несколько секунд

Техническая поддержка

Если у вас возникли вопросы по работе с API, проблемы с интеграцией или другие технические трудности — напишите нам на support@bot-gate.ru. Мы постараемся ответить как можно скорее.