مستندات پروکسی Bot API

آدرس پایه

به‌جای https://api.telegram.org از این آدرس استفاده کنید:

https://tg-proxy.eramcloud.com

احراز هویت پروکسی

هر اپلیکیشن یک کلید جدا دارد که از پنل ادمین ساخته می‌شود. بدون کلید معتبر، پروکسی درخواست را رد می‌کند.

روش پیشنهادی — هدر

X-Proxy-Key: tgp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

روش‌های جایگزین

Authorization: Bearer tgp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# یا (فقط در صورت اجبار)
GET /bot<token>/getMe?proxy_key=tgp_xxx

پارامتر proxy_key به تلگرام فوروارد نمی‌شود و قبل از ارسال حذف می‌گردد.

ساختار URL

https://tg-proxy.eramcloud.com/bot<BOT_TOKEN>/<METHOD>
https://tg-proxy.eramcloud.com/file/bot<BOT_TOKEN>/<FILE_PATH>

متدهای HTTP پشتیبانی‌شده

پروکسی این متدها را به تلگرام فوروارد می‌کند:

نمونه‌های درخواست

1) GET — بررسی ربات (getMe)

curl -X GET "https://tg-proxy.eramcloud.com/bot<BOT_TOKEN>/getMe" \
  -H "X-Proxy-Key: tgp_your_app_key"

2) GET — دریافت آپدیت‌ها با پارامتر Query

curl -X GET "https://tg-proxy.eramcloud.com/bot<BOT_TOKEN>/getUpdates?offset=0&limit=10&timeout=0" \
  -H "X-Proxy-Key: tgp_your_app_key"

3) POST JSON — ارسال پیام (sendMessage)

curl -X POST "https://tg-proxy.eramcloud.com/bot<BOT_TOKEN>/sendMessage" \
  -H "X-Proxy-Key: tgp_your_app_key" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": 123456789,
    "text": "سلام از پروکسی",
    "parse_mode": "HTML"
  }'

4) POST form-urlencoded

curl -X POST "https://tg-proxy.eramcloud.com/bot<BOT_TOKEN>/sendMessage" \
  -H "X-Proxy-Key: tgp_your_app_key" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "chat_id=123456789&text=Hello%20from%20proxy"

5) POST multipart — ارسال عکس (sendPhoto)

curl -X POST "https://tg-proxy.eramcloud.com/bot<BOT_TOKEN>/sendPhoto" \
  -H "X-Proxy-Key: tgp_your_app_key" \
  -F "chat_id=123456789" \
  -F "caption=تصویر تست" \
  -F "photo=@/path/to/image.jpg"

6) POST — تنظیم وب‌هوک (setWebhook)

curl -X POST "https://tg-proxy.eramcloud.com/bot<BOT_TOKEN>/setWebhook" \
  -H "X-Proxy-Key: tgp_your_app_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.example.com/telegram/webhook",
    "max_connections": 40,
    "allowed_updates": ["message", "callback_query"]
  }'

7) GET — دانلود فایل

ابتدا با getFile مسیر فایل را بگیرید، سپس:

curl -X GET "https://tg-proxy.eramcloud.com/file/bot<BOT_TOKEN>/photos/file_0.jpg" \
  -H "X-Proxy-Key: tgp_your_app_key" \
  -o file.jpg

8) متدهای پرکاربرد دیگر

لیست کامل متدها مطابق Telegram Bot API است؛ پروکسی فقط لایه انتقال و احراز هویت اضافه می‌کند.

پاسخ‌ها و خطاها

{
  "ok": false,
  "error_code": 401,
  "description": "Unauthorized"
}

نمونه‌کد کلاینت

Python (requests)

import requests

BASE = "https://tg-proxy.eramcloud.com"
KEY = "tgp_your_app_key"
TOKEN = "123456:ABC-DEF"

r = requests.post(
    f"{BASE}/bot{TOKEN}/sendMessage",
    headers={"X-Proxy-Key": KEY},
    json={"chat_id": 123456789, "text": "hello"},
    timeout=30,
)
print(r.json())

PHP (cURL)

$url = "https://tg-proxy.eramcloud.com/bot{$token}/sendMessage";
$ch = curl_init($url);
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    "X-Proxy-Key: {$proxyKey}",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "chat_id" => 123456789,
    "text" => "hello",
  ]),
  CURLOPT_RETURNTRANSFER => true,
]);
echo curl_exec($ch);

Laravel (HTTP Client)

Http::withHeaders(["X-Proxy-Key" => config("services.telegram.proxy_key")])
    ->post(
        config("services.telegram.proxy_base") . "/bot" . config("services.telegram.bot_token") . "/sendMessage",
        ["chat_id" => 123456789, "text" => "hello"]
    );

python-telegram-bot

Application.builder() \
    .token(TOKEN) \
    .base_url("https://tg-proxy.eramcloud.com/bot") \
    .base_file_url("https://tg-proxy.eramcloud.com/file/bot") \
    .build()

هدر X-Proxy-Key را از طریق HTTPXRequest(httpx_kwargs={"headers": {...}}) پاس بدهید. جزئیات بیشتر در پوشه examples/ پروژه.