مستندات Ghasedak Bot API 🤖

آدرس پایه

همه درخواست‌ها POST هستند (GET هم پذیرفته می‌شود) و این شکل را دارند:

https://ghsdk.ir/bot<token>/METHOD

# مثال: گرفتن اطلاعات خود ربات
$ curl -X POST "https://ghsdk.ir/bot<token>/getMe"

احراز هویت

ربات‌ها از کاربران عادی جدا هستند: لاگین OTP/ایمیل ندارند و فقط با توکن احراز می‌شوند:

<bot_user_id UUID>:<32 hex chars>

• توکن در URL قرار می‌گیرد؛ هرگز آن را در مخازن عمومی commit نکنید.
• توکن تا زمان /revoke معتبر می‌ماند و چند کلاینت همزمان پشتیبانی می‌شود.
• بات‌ها presence ندارند (آنلاین/آخرین‌بازدید معنا ندارد) و به فیچرهای انسانی مانند گیفت و تماس دسترسی ندارند.
• کاربر باید ابتدا به بات پیام دهد (چت بسازد)؛ سپس بات می‌تواند پاسخ دهد.

قالب پاسخ

پاسخ همه متدها JSON است با همین قالب (مطابق تلگرام):

{
  "ok": true,
  "result": { ... }
}

در صورت خطا:

{
  "ok": false,
  "error_code": 401,
  "description": "Unauthorized: invalid bot token"
}

Quick Start

curl

$ curl -X POST "https://ghsdk.ir/bot$BOT_TOKEN/sendMessage" \
     -H "Content-Type: application/json" \
     -d '{"chat_id":"<chat_uuid>", "text":"سلام از BargBot! 🌾"}'

Python — long polling کامل

import json, urllib.request

API = "https://ghsdk.ir/bot<token>"
offset = 0

def call(method, payload=None, timeout=40):
    req = urllib.request.Request(
        f"{API}/{method}",
        data=json.dumps(payload or {}).encode(),
        headers={"Content-Type": "application/json"})
    with urllib.request.urlopen(req, timeout=timeout) as r:
        out = json.load(r)
    if not out["ok"]:
        raise RuntimeError(out["description"])
    return out["result"]

while True:
    updates = call("getUpdates", {"offset": offset, "timeout": 25}, timeout=35)
    for u in updates:
        offset = u["update_id"] + 1
        msg = u.get("message") or {}
        if msg.get("text") == "/start":
            call("sendMessage", {"chat_id": msg["chat"]["id"],
                                  "text": "سلام! 👋"})

متدها

getMe

اطلاعات هویتی خود ربات — برای تست سلامت توکن عالی است. بدون پارامتر.

{
  "ok": true,
  "result": {
    "id": "42d67200-beac-4ada-b9a0-ea06d64a0f38",
    "is_bot": true,
    "first_name": "BargBot",
    "username": "bargbot"
  }
}

sendMessage

ارسال پیام متنی. بات باید عضو چت باشد؛ در چت خصوصی یعنی کاربر قبلاً به بات پیام داده باشد.

{
  "ok": true,
  "result": {
    "message_id": "fe9c4526-6ad9-486d-b0cd-a569f739f2d8",
    "from": {
      "id": "42d67200-beac-4ada-b9a0-ea06d64a0f38",
      "is_bot": true,
      "first_name": "BargBot",
      "username": "bargbot"
    },
    "chat": {
      "id": "24a7b58b-eb91-4f7b-8d75-fab23fc35e80",
      "type": "private"
    },
    "date": 1787434922,
    "text": "سلام! 👋",
    "media_type": "text"
  }
}

sendPhoto

ارسال تصویر با کپشن اختیاری.

sendVideo

ارسال ویدیو (mp4/webm). همان ساختار sendPhoto ولی فیلد مدیا video است.

$ curl -X POST "https://ghsdk.ir/bot$BOT_TOKEN/sendVideo" \
     -H "Content-Type: application/json" \
     -d '{"chat_id":"<chat_uuid>",
          "video":"https://ghsdk.ir/media/abc.mp4",
          "caption":"خروجی ربات 🎬"}'

editMessageText

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

پاسخ: آبجکت پیامِ به‌روزشده.

deleteMessage

حذف یک پیامِ فرستاده‌شده توسط بات. پاسخ {"ok":true,"result":true}.

getChat

اطلاعات پایه یک چت که بات در آن عضو است.

{
  "ok": true,
  "result": {
    "id": "24a7b58b-eb91-4f7b-8d75-fab23fc35e80",
    "type": "private"
  }
}

در گروه/کانال فیلدهای title و username هم برمی‌گردند.

getChatMember

وضعیت و نقش یک عضو در چت.

{
  "ok": true,
  "result": {
    "user": {
      "id": "de17273b-717d-4e40-bf00-fd33cc316868",
      "is_bot": false,
      "first_name": "taha",
      "username": "iTahaSm"
    },
    "status": "creator"
  }
}

status یکی از: creator | administrator | member | left

getUpdates

دریافت پیام‌ها و رویدادهای رسیده به بات با long polling — تنها راه دریافت آپدیت‌ها. اگر آپدیتی نباشد، درخواست تا رسیدن آپدیت جدید یا پایان timeout باز می‌ماند (حداکثر ۵۵ ثانیه).

{
  "ok": true,
  "result": [
    {
      "update_id": 31,
      "message": {
        "message_id": "4657574f-bd55-45b3-aa96-99bd5a03b636",
        "from": { "id": "48fc529c-db75-4d58-827a-0308eed543a7", "is_bot": false, "first_name": "" },
        "chat": { "id": "24a7b58b-eb91-4f7b-8d75-fab23fc35e80", "type": "private" },
        "date": 1787434922,
        "text": "/start",
        "media_type": "text"
      }
    }
  ]
}

فیلدهای مهم message:

• from.photo_url، from.username — اکستنشن قاصدک (در تلگرام نیست)
• media_type: ‏text | image | video | voice | audio | file | sticker | system | gift
• media_url، caption — برای پیام‌های مدیا
• reply_to_message — پیام والد در صورت ریپلای
• chat.type: ‏private | group | channel

حریم خصوصی گروهی (Privacy Mode)

مثل تلگرام، به‌صورت پیش‌فرض بات در گروه‌ها فقط این‌ها را دریافت می‌کند:

• کامندها (/start@botname)؛ اگر تنها باتِ گروه باشد، کامند بدون منشن هم کافی است
• ریپلای‌های مستقیم به پیام‌های خود بات
• پیام‌های سیستمی (عضویت، خروج و…)

برای بات‌هایی مثل دانلودر که باید همه پیام‌ها را ببینند، در @BotFather@ دستور /setprivacy را بزنید و حالت disable را انتخاب کنید. تغییر بلافاصله اعمال می‌شود.

upload

آپلود فایل برای استفاده در sendPhoto / sendVideo — معادل POST /v1/upload اما با احراز توکن بات. بدنه multipart با فیلد file:

$ curl -X POST "https://ghsdk.ir/bot$BOT_TOKEN/upload" \
     -F "file=@/path/to/video.mp4;type=video/mp4"

{
  "ok": true,
  "result": {
    "url": "https://ghsdk.ir/media/4db977a9-c208-464c-8d71-942476807d1f.mp4",
    "media_width": 0,
    "media_height": 0,
    "media_duration": 0
  }
}

• حداکثر حجم: ۵۰ مگابایت
• فرمت‌های مجاز: jpg، png، webp، gif (تصویر) — mp3، ogg، wav، m4a (صدا) — mp4، webm (ویدیو)
• نوع واقعی فایل از محتوا تشخیص داده می‌شود، نه از هدر ادعایی
• فیلدهای اختیاری width، height، duration را هم می‌توانید بفرستید

منوی کامندها

setMyCommands

تنظیم منوی کامندهای عمومی بات که در کلاینت نمایش داده می‌شود.

$ curl -X POST "https://ghsdk.ir/bot$BOT_TOKEN/setMyCommands" \
     -H "Content-Type: application/json" \
     -d '{"commands":[{"command":"start","description":"شروع کار"},
                      {"command":"help","description":"راهنما"}]}'

getMyCommands

دریافت منوی فعلی. بدون پارامتر؛ پاسخ آرایه‌ای از {command, description}.

متدهای متفرقه

محدودیت‌ها

خطاهای رایج و رفع آن‌ها

مرجع BotFather@

مدیریت بات‌ها داخل خود پیام‌رسان، با پیام دادن به @BotFather@: