Bot API جترا

مستندات ربات‌های جترا

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

آماده استفاده در برنامه

ربات‌های رسمی جترا

ربات‌ساز جترا

@BotFather

ساخت ربات، دریافت یا تعویض توکن و مدیریت نام، توضیحات، فرمان‌ها، حریم خصوصی و دسترسی گروه.

استیکرساز جترا

@Stickers

ساخت و مدیریت بسته‌های استیکر و ایموجی سفارشی، افزودن یا حذف مورد و انتشار بسته.

تأیید رسمی جترا

@verifybot

ثبت و پیگیری درخواست تأیید رسمی برای ربات، کانال یا سوپرگروه عمومی در جترا.

شناسه‌یاب جترا

@Userinfo_bot

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

شروع سریع

  1. در جترا وارد @BotFather شوید و فرمان /newbot را ارسال کنید.
  2. نام نمایشی و سپس نام کاربری ربات را انتخاب کنید.
  3. توکن ساخته‌شده را در متغیر امن سرور خود نگه دارید.
  4. با درخواست زیر اتصال را آزمایش کنید.
curl "https://jetra.ir/bot<TOKEN>/getMe"

پاسخ موفق همیشه شامل ok: true و نتیجه در فیلد result است.

دریافت پیام‌ها

برای شروع ساده از long polling استفاده کنید. رویدادهای فعلی جترا شامل message، edited_message و callback_query هستند.

curl -X POST "https://jetra.ir/bot<TOKEN>/getUpdates" \
  -H "Content-Type: application/json" \
  -d '{"offset":0,"limit":100,"timeout":30}'

بعد از پردازش هر رویداد، درخواست بعدی را با offset = update_id + 1 بفرستید. هم‌زمان نمی‌توان از polling و webhook استفاده کرد.

ارسال پیام و دکمه

درخواست‌ها می‌توانند JSON، فرم معمولی یا برای بارگذاری فایل multipart/form-data باشند.

curl -X POST "https://jetra.ir/bot<TOKEN>/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": 123456789,
    "text": "سلام از ربات جترا",
    "reply_markup": {
      "inline_keyboard": [[
        {"text":"تأیید","callback_data":"confirm"}
      ]]
    }
  }'

Webhook

برای محیط عملیاتی، یک نشانی عمومی HTTPS ثبت کنید. جترا هر رویداد را به‌صورت JSON با درخواست POST ارسال می‌کند.

curl -X POST "https://jetra.ir/bot<TOKEN>/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{
    "url":"https://example.com/jetra-webhook",
    "secret_token":"YOUR_WEBHOOK_SECRET",
    "allowed_updates":["message","edited_message","callback_query"]
  }'

در صورت تعیین رمز، آن را از هدر X-Jetra-Bot-Api-Secret-Token بررسی کنید.

مرجع متدهای موجود

نام متدها به حروف بزرگ و کوچک حساس نیست. همه آن‌ها با همان توکن BotFather فراخوانی می‌شوند.

حساب و فرمان‌ها

getMeبررسی توکن و دریافت مشخصات ربات
setMyCommandsثبت فهرست فرمان‌های ربات
deleteMyCommandsحذف فرمان‌های ثبت‌شده
getMyCommandsدریافت فرمان‌های فعلی

دریافت رویدادها

getUpdatesدریافت پیام‌ها با long polling
setWebhookارسال رویدادها به نشانی HTTPS شما
deleteWebhookحذف webhook و بازگشت به polling
getWebhookInfoنمایش وضعیت و خطای آخر webhook

ارسال محتوا

sendMessageارسال پیام متنی
sendRichMessageارسال پیام غنی اختصاصی جترا
sendPhotoارسال عکس
sendAnimationارسال پویانمایی
sendAudioارسال فایل صوتی
sendDocumentارسال فایل
sendLivePhotoارسال Live Photo جترا
sendStickerارسال استیکر
sendVideoارسال ویدئو
sendVideoNoteارسال پیام ویدئویی گرد
sendVoiceارسال پیام صوتی
sendContactارسال مخاطب
sendLocationارسال موقعیت مکانی
sendVenueارسال مکان همراه با عنوان و نشانی

مدیریت پیام و دکمه‌ها

editMessageTextویرایش متن پیام
deleteMessageحذف پیام
answerCallbackQueryپاسخ به کلیک دکمه درون‌خطی
getFileدریافت مسیر دانلود فایل

پیام موقت اختصاصی جترا

editEphemeralMessageTextویرایش متن پیام موقت
editEphemeralMessageMediaویرایش رسانه پیام موقت
editEphemeralMessageCaptionویرایش توضیح پیام موقت
editEphemeralMessageReplyMarkupویرایش دکمه‌های پیام موقت
deleteEphemeralMessageحذف پیام موقت

منو و مینی‌اپ

setChatMenuButtonتنظیم دکمه منوی گفت‌وگوی ربات
getChatMenuButtonدریافت دکمه منوی فعلی
setUserEmojiStatusتنظیم وضعیت ایموجی کاربر با مجوز او
answerWebAppQueryپاسخ به درخواست مینی‌اپ
savePreparedInlineMessageذخیره پیام آماده برای اشتراک‌گذاری از مینی‌اپ

محدودیت‌ها و امنیت

  • توکن، رمز کنترل ربات است؛ آن را در کد عمومی، مخزن یا پیام منتشر نکنید. در صورت افشا از /revoke استفاده کنید.
  • حداکثر اندازه هر فایل بارگذاری‌شده ۲۵ مگابایت است.
  • getUpdates حداکثر ۱۰۰ رویداد و timeout حداکثر ۵۰ ثانیه می‌پذیرد.
  • Webhook فقط با HTTPS عمومی پذیرفته می‌شود؛ از secret_token استفاده کنید.
  • فقط متدهای فهرست‌شده در همین صفحه پشتیبانی می‌شوند.
  • answerInlineQuery، پرداخت، answerShippingQuery و answerPreCheckoutQuery در HTTP API فعلی قابل استفاده نیستند.