مستندات Bot API چاپار

📌 معرفی

هر ربات یک حساب کاربری معمولی در چاپار است (با نشان «ربات») که از طریق یک توکن API کنترل می‌شود. کاربران می‌توانند به ربات پیام خصوصی بدهند یا آن را به گروه‌ها اضافه کنند؛ سرورِ شما با توکن، پیام‌ها را دریافت و پاسخ می‌دهد.

برای ساخت ربات، از داخل چاپار گفتگوی خصوصی با @botfather را باز کنید و دستور /newbot را بفرستید. سایر دستورهای مفید: /mybots ، /token ، /revoke ، /deletebot.

🚀 شروع سریع

آدرس پایه

کافی است توکن ربات خود را جای <token> و نام متد را جای <method> بگذارید؛ مثال: …/bot12345:ABC…/sendMessage

ارسال درخواست

• همهٔ متدها با GET یا POST فراخوانی می‌شوند.
• پارامترها به‌صورت form-data ، query string یا بدنهٔ JSON قابل ارسال‌اند.
• به‌جای قرار دادن توکن در مسیر، می‌توانید آن را در هدر بفرستید: Authorization: Bearer <token>

قالب پاسخ

// موفق
{"ok": true, "result": ...}

// خطا (+ کد HTTP مناسب)
{"ok": false, "error_code": 401, "description": "Invalid bot token"}

getMe

اطلاعات خودِ ربات را برمی‌گرداند. برای تست صحت توکن مناسب است.

{"ok":true,"result":{"id":3657999999999999,"username":"myshop_bot","name":"ربات فروشگاه"}}

sendMessage

ارسال پیام متنی. یکی از user_id یا chat_id الزامی است.

POST /bot<token>/sendMessage
chat_id=123&text=سفارش ثبت شد

{"ok":true,"result":{"message_id":3658000000000000,"chat_id":123}}

editMessage

ویرایش متن پیام‌هایی که خودِ ربات فرستاده است.

{"ok":true,"result":{"message_id":3658000000000000,"chat_id":123,"edited_at":"2026-08-24 12:00:00"}}

deleteMessage

حذف پیام. ربات همیشه می‌تواند پیام‌های خودش را حذف کند؛ حذف پیام دیگران فقط وقتی ممکن است که ربات در آن گروه مدیر یا ناظم باشد.

{"ok":true,"result":{"message_id":3658000000000000,"chat_id":123,"deleted":true}}

getUpdates

دریافت پیام‌ها و کلیک دکمه‌ها با الگوی Long Polling. خروجی دو نوع update دارد:

• message — پیام خصوصی کاربران یا پیام گروه‌هایی که ربات عضوشده
• callback_query — کلیک روی دکمهٔ شیشه‌ای (شامل from ، message ، data)

{"ok":true,"result":[
  {"update_id": 3658000000000001,
   "message": {"message_id": 3658000000000001,
               "from": {"id": 5, "username": "aydin", "name": "Aydin"},
               "chat": {"id": 3658000000000000, "type": "private", "title": "@aydin"},
               "date": 1771000000, "text": "سلام",
               "photo": null, "document": null, "document_name": null,
               "location": null, "reply_to": 0}},
  {"update_id": 3658000000000002,
   "callback_query": {"id": "3658000000000002",
                     "from": {"id": 5, "username": "aydin", "name": "Aydin"},
                     "message": {"message_id": 3657999999999999,
                                 "chat": {"id": 3658000000000000, "type": "private"}},
                     "data": "ok_12"}}
]}

• الگوی مصرف: offset = update_id آخرین آیتم پردازش‌شده + 1 — پیام و callback یک شمارندهٔ مشترک دارند.
• با timeout=25 نیازی به حلقهٔ فشرده نیست؛ callbackهای تأییدشده خودکار پاک می‌شوند.

⌨️ دکمه‌های شیشه‌ای (Inline Keyboard)

با پارامتر reply_markup در sendMessage و editMessage می‌توانید زیر پیام دکمه اضافه کنید. هر دکمه یا لینک دارد (url) یا داده (callback_data) که کلیک آن از طریق getUpdates به ربات می‌رسد:

{"inline_keyboard": [
  [{"text": "تأیید سفارش", "callback_data": "ok_12"},
   {"text": "وب‌سایت ما", "url": "https://example.com"}],
  [{"text": "رد سفارش", "callback_data": "no_12"}]
]}

• حداکثر ۸ ردیف، هر ردیف ۸ دکمه.
• متن هر دکمه تا ۶۴ نویسه؛ callback_data تا ۶۴ بایت.
• هر دکمه باید دقیقاً یکی از url یا callback_data را داشته باشد.
• روی هر دکمه هر کاربر چند بار قابل کلیک است؛ تپ تکراری همان کاربر روی همان دکمه صف اضافی نمی‌سازد.

⚠️ کدهای خطا

🐍 نمونهٔ کامل ربات (Python)

import time, requests

TOKEN = "3658...:abcd1234..."
API   = f"https://web.chaapar.ir/bot{TOKEN}"
offset = 0

while True:
    updates = requests.post(f"{API}/getUpdates",
                            data={"offset": offset, "timeout": 25}, timeout=30).json()
    for upd in updates.get("result", []):
        offset = upd["update_id"] + 1          # مهم: جلو بردن اشاره‌گر
        if "message" in upd:
            msg = upd["message"]
            if msg["text"].startswith("/start"):
                requests.post(f"{API}/sendMessage", data={
                    "chat_id": msg["chat"]["id"],
                    "text": "به ربات فروشگاه خوش آمدید!",
                    "reply_markup": '{"inline_keyboard":[[{"text":"محصولات","url":"https://example.com"},{"text":"پشتیبانی","callback_data":"support"}]]}',
                })
        elif "callback_query" in upd:
            cb = upd["callback_query"]
            if cb["data"] == "support":
                requests.post(f"{API}/sendMessage", data={
                    "chat_id": cb["message"]["chat"]["id"],
                    "text": "تیم پشتیبانی خبرتان می‌کند.",
                })
    if not updates.get("result"):
        time.sleep(0.5)

🔐 نکات امنیتی

• توکن معادل گذرواژهٔ ربات است؛ هر کس آن را داشته باشد می‌تواند به‌جای ربات پیام بفرستد.
• اگر توکن لو رفت، فوراً از بات‌فادر با /revoke توکن جدید بگیرید.
• در سمت سرور، توکن را در متغیر محیطی نگه دارید — نه داخل کد یا مخزن.
• پیام‌های چاپار رمزنگاری چندلایه دارند؛ رمزگشایی فقط روی سرور انجام می‌شود و کلاینت شما متن رمزگشایی‌شده را دریافت می‌کند.