API بازوی بله بر اساس HTTP ساخته شده تا توسعه‌دهندگان علاقه‌مند بتوانند به آسانی در بله بازو ایجاد کنند.

اجازه دسترسی برای بازو

در اولین مرحله ساخت بازو باید با بازوی پدر به نشانی @botfather در بله گفتگو کنید و بازوی خودتان را بسازید. هنگام ساخت بازو، توکن احراز هویت منحصر به فردی به آن تعلق می‌گیرد. توکن‌ها با فرمتی مشابه 123456:ABC-DEF1234ghIkl-zyx68W2v1u123ew12 هستند.

ایجاد درخواست

تمامی درخواست‌های مربوط به API بازوی بله باید در بستر HTTPS و به این شکل https://tapi.bale.ai/bot<token>/METHOD_NAME (opens in a new tab) فراخوانی شوند. برای مثال به درخواست زیر توجه کنید:

درخواست (opens in a new tab)

متد‌های GET و POST را پشتیبانی می‌شوند. همچنین از چهار روش زیر برای ارسال پارامتر در ریکوئست‌های بازوی بله پشتیبانی می‌شود:

  • URL query string

  • application/x-www-form-urlencoded

  • application/json (به جز برای آپلود فایل)

  • multipart/form-data (برای آپلود فایل استفاده کنید)

پاسخ حاوی یک شیء JSON است، که همیشه یک فیلد 'ok' از جنس boolean دارد و ممکن است فیلد توضیحات (description) که برای توضیح نتیجه‌ی درخواست است، داشته باشد. اگر فیلد ‘ok’ معادل true باشد، به این معنی هست که درخواست موفق بوده و نتیجه درخواست را می‌توان در فیلد ‘result’ یافت. در زمان ناموفق بودن درخواست، مقدار فیلد ‘ok’ برابر false بوده و خطا در ‘description’ توضیح داده می‌شود. یک فیلد ‘error_code’ از جنس integer نیز در پاسخ درخواست وجود دارد، که ممکن است مقدار آن در آینده تغییر کند. برخی از خطاها ممکن است یک فیلد اختیاری ‘parameters’ از نوع ResponseParameters داشته ‌باشند، که می‌تواند به مدیریت خودکار خطا کمک کند.

  • هیچ حساسیتی نسبت به بزرگ یا کوچک بودن حروف در API بازوی بله وجود ندارد. همه درخواست‌ها باید با فرمت UTF-8 ایجاد شوند.

ایجاد درخواست پس از دریافت آپدیت‌ها

از یکی از content-typeهای application/json یا application/x-www-form-urlencoded یا multipart/form-data برای ارسال پارامترها استفاده کنید. متد درخواست خود را از طریق پارامتر method مشخص کنید. اطلاع از آن‌که آیا چنین درخواستی موفق بوده و یا دستیابی به نتیجه‌ی آن امکان‌پذیر نیست.

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

دو روش مجزا برای دریافت آپدیت‌ها در بازو وجود دارد:
۱- getUpdates
۲- وب‌هوک

آپدیت‌های دریافتی تا زمانی که بازو از طریق یکی از روش‌های بالا آن‌ها را دریافت کند در سرور ذخیره می‌شوند. در حال حاضر 2000 پیام آخر به مدت ۲۴ ساعت نگهداری می‌شود.

در هر دو روش، آپدیت‌ها در قالب یک شیء JSON یکسان دریافت می‌شوند.

Update

این شیء بیانگر یک آپدیت دریافتی است. برای هر اتفاق در گفتگوها و پیام های بازو یک آپدیت مجزا ایجاد می‌شود و هر آپدیت صرفا میتواند یک نوع داده را داشته باشد. حداکثر یکی از پارامترهای اختیاری می‌تواند در هر آپدیت داده شده وجود داشته باشد. به طور مثال یک آپدیت نمی تواند همزمان message و callback_query را داشته باشد.

فیلدنوعشرح
update_idIntegerشناسه منحصربه‌فرد آپدیت. شناسه‌های آپدیت از صفر آغاز شده و به ترتیب افزایش می‌یابند. این ID مخصوصا زمانی به کار می‌آید که از وب‌هوک استفاده کنید، زیرا به شما اجازه می‌دهد که آپدیت‌های تکراری را نادیده گرفته و یا اگر از ترتیب خارج شده ‌باشند، دنباله آپدیت درست را بازیابی کنید.
messageMessageاختیاری. پیام‌ دریافتی جدید از هر نوعی – متن، تصویر، استیکر و غیره
edited_messageMessageاختیاری. نسخه ویرایش شده پیامی که در گذشته برای بازو ارسال شده است.
callback_queryCallbackQueryاختیاری. callback query دریافتی جدید.هنگامی که بر روی دکمه های inline پیام ها کلیک می شود، یک آپدیت دارای این فیلد ارسال می شود. فیلد data در شئ CallBackQuery برابر با مقداری است که هنگام تعریف دکمه مشخص می شود.

getUpdates

از این متد برای دریافت آپدیت‌ها با استفاده از long polling استفاده کنید. این متد آرایه‌ای از Update را باز می‌گرداند.

پارامترنوعالزامتوضیحات
offsetIntegerاختیاریشناسه اولین آپدیتی که باید برگردانده شود. باید یک واحد بیشتر از بیشترین مقدار شناسه‌های مربوط به Update های دریافتی قبلی باشد. به طور پیش‌فرض، ابتدا Update هایی بازگشت داده می شوند که اولین Update تایید نشده را دارند . به محض اینکه getUpdates با یک offset بیشتر از update_id خود فراخوانی شود، Update به صورت تایید شده در نظر گرفته خواهد شد. از مقدار offset منفی هم می‌توان استفاده کرد. از مقدار منفی offset میتوان برای دریافت Update ها از انتهای صف Update ها استفاده کرد. تمام Update های قبلی فراموش خواهند شد.
limitIntegerاختیاریتعداد Update های که باید دریافت شوند را محدود می‌کند. مقادیر بین ۱ تا ۱۰۰ قابل قبول هستند. مقدار پیش‌فرض برابر با ۱۰۰ است.

نکته: به منظور جلوگیری از Update های تکراری، مقدار offset را بعد از هر پاسخ سرور، مجدد حساب کنید.

setWebhook

از این متد برای تعیین یک URL وب‌هوک خروجی استفاده می شود که از طریق آن Updateها دریافت می‌شود. زمانی که یک Update برای بازو وجود دارد، یک درخواست HTTPS POST به URL‌ مشخص‌شده ارسال خواهد شد که حاوی آپدیت JSON-serialized است. خروجی این متد در صورت اجرای موفقیت‌آمیز True است.

پارامترنوعالزامتوضیحات
urlstringالزامیآدرس HTTPS URL ای که Update ها باید به آن ارسال شوند. برای حذف یکپارچه‌سازی (غیرفعال کردن) وب‌هوک, یک رشته خالی را ارسال کنید.

نکته: درگاه‌هایی(ports) که در حال حاضر برای وب‌هوک پشتیبانی می‌شوند، عبارتند از: 443, 88.

getWebhookInfo

از این متد برای دریافت وضعیت فعلی وب‌هوک استفاده کنید. این متد به هیچ پارامتری نیاز ندارد. در صورت اجرای موفقیت آمیز، یک شی WebhookInfo برگردانده می‌شود. اگر بازو در حال استفاده از متد getUpdates است، خروجی یک شی خواهد بود که فیلد url آن خالی است.

WebhookInfo

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

فیلدنوعتوضیحات
urlstringURL مربوط به وب‌هوک، در صورتی که وب‌هوک تنظیم نشده باشد، خالی خواهد بود.

انواع موجود

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

برای ذخیره سازی تمام اعداد(integers)، استفاده از اعداد صحیح علامت‌دار ۳۲ بیتی کافی است، مگر اینکه به مورد دیگری برای این منظور اشاره شده باشد.

اختیاری: فیلدهای اختیاری بسته به شرایط، ممکن است در خروجی برگردانده نشوند. به طور مثال در صورتی که اطلاعات مربوط به گفتگو شخصی باشد، مقدار first_name وجود دارد ولی در اطلاعات گفتگوهای دیگر این مقدار خالی است.

User

این شی نشان‌دهنده یک کاربر بله یا یک بازو است.

فیلدنوعتوضیحات
idIntegerاختیاری. می‌تواند بیشتر از ۲۳۱ باشد و برخی زبان‌های برنامه‌نویسی ممکن است در تفسیر آن با مشکل روبه‌رو شوند. اما این فیلد حداکثر ۵۲ بیت با ارزش اهمیت دارد و فرمت ۶۴ بیتی علامت‌دار عدد صحیح یا عدد اعشاری ۶۴ بیتی برای ذخیره‌سازی آن مناسب است.
is_botBooleanاگر کاربر، یک بازو باشد، مقدار آن True است.
first_namestringنام کوچک کاربر یا بازو
last_namestringاختیاری. نام خانوادگی کاربر یا بازو
usernamestringاختیاری. نام کاربری کاربر یا بازو
language_codestringاختیاری. برچسب زبانی IETF برای زبان کاربر

Chat

این شی نشان‌دهنده یک گفتگو است.

فیلدنوعتوضیحات
idIntegerشناسه یکتای چت. می‌تواند بیشتر از ۲۳۱ باشد و برخی زبان‌های برنامه‌نویسی ممکن است در تفسیر آن با مشکل روبه‌رو شوند. اما این فیلد حداکثر ۵۲ بیت با ارزش اهمیت دارد و فرمت ۶۴ بیتی علامت‌دار عدد صحیح یا عدد اعشاری ۶۴ بیتی برای ذخیره‌سازی آن مناسب است.
typestringنوع گفتگو که می‌تواند یکی از موارد "private”، “group” یا “channel” باشد.
titlestringاختیاری. عنوان گفتگو‌های داخل گروه‌ها یا کانال‌ها
usernamestringاختیاری. نام کاربری برای گفتگو‌های خصوصی یا کانال‌ها در صورت وجود
first_namestringاختیاری. نام کوچک طرف دیگر در یک گفتگوی خصوصی
last_namestringاختیاری. نام خانوادگی طرف دیگر در یک گفتگوی خصوصی
photoChatPhotoاختیاری. تصویر گفتگو. فقط از طریق getChat بدست می‌آید.

Message

این شی نشان‌دهنده یک پیام است.

فیلدنوعتوضیحات
message_idIntegerشناسه منحصربه‌فرد پیام در داخل این گفتگو
fromUserاختیاری. کاربر ارسال‌کننده‌ی پیام. برای پیام‌هایی که در کانال ارسال می‌شوند، مقدار آن خالی است.
dateIntegerتاریخی که پیام ارسال شده است (در قالب زمان یونیکس)
chatChatاطلاعات گفتگویی که پیام به آن تعلق دارد.
forward_fromUserاختیاری. برای پیام‌های باز ارسال شده که ارسال‌کننده‌ی پیام اصلی را نشان می‌دهد
forward_from_chatChatاختیاری. برای پیام های باز ارسال شده که اطلاعات مربوط به گفتگوی اصلی پیام را نشان می‌دهد و در کانال‌ها, از طرف مدیران ناشناس است
forward_from_message_idIntegerاختیاری. شناسه پیام اصلی در کانال، برای پیام‌های باز ارسال شده از کانال‌ها
forward_dateIntegerاختیاری. برای پیام های باز ارسال شده , تاریخی که پیام اصلی در آن زمان ارسال شده است (در قالب زمان یونیکس)
reply_to_messageMessageاختیاری. پیام اصلی که روی آن پاسخی داده شده است. توجه داشته باشید که حتی اگر خود شی Message در این فیلد، یک پاسخ به پیام باشد، این فیلد مقدار دهی نمی‌شود.
edite_dateIntegerاختیاری. تاریخ آخرین باری که پیام ویرایش شده است (در قالب زمان یونیکس)
textStringاختیاری. متن واقعی پیام با فرمت UTF-8 برای پیام‌های متنی
animationAnimationاختیاری برای پیام‌های که تصویر متحرک دارند این فیلد پر می شود و اطلاعاتی در مورد انیمیشن می‌دهد. برای سازگاری عقب‌رو، زمانی که این فیلد تنظیم شود، فیلد document نیز تنظیم خواهد شد.
audioAudioاختیاریبرای پیام‌هایی که به صورت فایل صوتی هستند این فیلد با اطلاعات فایل مقدار دهی می شود.
documentDocumentاختیاری. برای پیام‌هایی که به صورت فایل عمومی هستند، اطلاعاتی در مورد فایل می‌دهد.
photoآرایه‌ای از PhotoSizeاختیاری. برای پیام‌هایی که به صورت تصویر هستند، اندازه‌های موجود برای تصویر را می‌دهد.
stickerStickerاختیاری. برای پیام‌هایی که به صورت استیکر هستند، اطلاعاتی در مورد استیکر می‌دهد.
videoVideoاختیاری. برای پیام‌هایی که به صورت ویدیو هستند، اطلاعاتی در مورد ویدیو می‌دهد.
voiceVoiceاختیاری. برای پیام‌های صوتی، اطلاعاتی در مورد فایل می‌دهد.
captionStringاختیاری. توضیحات مربوط به انیمیشن، فایل صوتی، سند، تصویر، ویدیو یا پیام صوتی
contactContactاختیاری. در صورتی که پیام یک مخاطب به اشتراک‌گذاشته‌شده باشد، اطلاعاتی در مورد مخاطب می‌دهد.
locationLocationاختیاری. اگر پیام یک موقعیت به اشتراک‌گذاشته‌شده باشد، اطلاعاتی در مورد این موقعیت می‌دهد.
new_chat_membersآرایه‌ای از Userاختیاری.اطلاعاتی در مورد اعضای جدیدی که به گروه اضافه شده‌اند می دهد (خود بازو می‌تواند یکی از این اعضا باشد)
left_chat_memberUserاختیاری. عضوی که از گروه حذف یا خارج شده است و اطلاعاتی در مورد آن (این عضو می‌تواند خود بازو باشد)
invoiceInvoiceاختیاری. در صورتی که پیام یک صورتحساب برای یک عملیات پرداخت باشد، اطلاعاتی در مورد صورتحساب می‌دهد.
successful_paymentSuccessfulPaymentاختیاری. در صورتی که پیام یک پرداخت موفق باشد ، اطلاعاتی در مورد پرداخت می‌دهد.
reply_markupInlineKeyboardMarkupاختیاری. صفحه‌کلید inline که به یک پیام پیوست شده است. کلیدهای login_url به عنوان کلیدهای url معمولی نشان داده می‌شوند.

MessageId

این شی نشان‌دهنده یک شناسه پیام منحصر‌به‌فرد است.

فیلدنوعتوضیحات
message_idIntegerشناسه پیام منحصر‌به‌فرد

PhotoSize

این شی یک اندازه از تصویر یا یک thumbnail از استیکر/فایل را نشان می‌دهد.

فیلدنوعتوضیحات
file_idStringشناسه این فایل که می‌توان آن‌ را جهت دانلود یا استفاده مجدد از فایل به کار برد.
file_unique_idStringشناسه منحصربه‌فرد این فایل است که در طول زمان و برای بازوهای مختلف یکسان است. نمی‌توان این شناسه را برای دانلود یا استفاده مجدد از فایل به کار برد.
widthIntegerپهنای تصویر
heightIntegerارتفاع تصویر
file_sizeIntegerاختیاری. حجم فایل با واحد بایت

Animation

این شی نشان‌دهنده یک فایل انیمیشن است (GIF یا ویدیو H.264/MPEG-4 AVC بدون صدا).

فیلدنوعتوضیحات
file_idStringشناسه این فایل که می‌توان آن‌ را جهت دانلود یا استفاده مجدد از فایل به کار برد.
file_unique_idStringشناسه منحصربه‌فرد این فایل که فرض می‌شود، در طول زمان و برای بازوهای مختلف یکسان است. نمی‌توان این شناسه را برای دانلود یا استفاده مجدد از فایل به کار برد.
widthIntegerپهنای تصویر ویدیو
heightIntegerارتفاع تصویر ویدیو
durationIntegerمدت زمان ویدیو به ثانیه
thumbnailPhotoSizeاختیاری. thumbnail انیمیشن
file_nameStringاختیاری. نام اصلی انیمیشن
mime_typeStringاختیاری. نوع MIME فایل
file_sizeIntegerاختیاری. حجم فایل با واحد بایت. می‌تواند بیشتر از ۲۳۱ باشد و برخی زبان‌های برنامه‌نویسی ممکن است در تفسیر آن با مشکل روبه‌رو شوند. اما این فیلد حداکثر ۵۲ بیت با ارزش اهمیت دارد و فرمت ۶۴ بیتی علامت‌دار عدد صحیح یا عدد اعشاری ۶۴ بیتی برای ذخیره‌سازی آن مناسب است.

Audio

این شی نشان‌دهنده یک فایل صوتی است.

فیلدنوعتوضیحات
file_idstringشناسه این فایل که می‌توان آن‌ را جهت دانلود یا استفاده مجدد از فایل به کار برد.
file_unique_idstringشناسه منحصربه‌فرد این فایل که فرض می‌شود، در طول زمان و برای بازوهای مختلف یکسان است. نمی‌توان این شناسه را برای دانلود یا استفاده مجدد از فایل به کار برد.
durationIntegerمدت زمان فایل صوتی به ثانیه.
titlestringاختیاری. عنوان فایل صوتی
file_namestringاختیاری. نام اصلی فایل
mime_typestringاختیاری. نوع MIME فایل
file_sizeIntegerاختیاری. حجم فایل با واحد بایت. می‌تواند بیشتر از ۲۳۱ باشد و برخی زبان‌های برنامه‌نویسی ممکن است در تفسیر آن با مشکل روبه‌رو شوند. اما این فیلد حداکثر ۵۲ بیت با ارزش اهمیت دارد و فرمت ۶۴ بیتی علامت‌دار عدد صحیح یا عدد اعشاری ۶۴ بیتی برای ذخیره‌سازی آن مناسب است.

Document

این شی به طور کلی نشان‌دهنده یک فایل است (بر خلاف تصاویر، پیام‌های صوتی و فایل‌های صوتی).

فیلدنوعتوضیحات
file_idStringشناسه این فایل که می‌توان آن‌ را جهت دانلود یا استفاده مجدد از فایل به کار برد.
file_unique_idStringشناسه منحصربه‌فرد این فایل که فرض می‌شود، در طول زمان و برای بازوهای مختلف یکسان است. نمی‌توان این شناسه را برای دانلود یا استفاده مجدد از فایل به کار برد.
thumbnailPhotoSizeاختیاری. thumbnail سند که توسط ارسال‌کننده تعریف شده است.
file_nameStringاختیاری. نام اصلی فایل
mime_typeStringاختیاری. نوع MIME فایل
file_sizeIntegerاختیاری. حجم فایل با واحد بایت. می‌تواند بیشتر از ۲۳۱ باشد و برخی زبان‌های برنامه‌نویسی ممکن است در تفسیر آن با مشکل روبه‌رو شوند. اما این فیلد حداکثر ۵۲ بیت با ارزش اهمیت دارد و فرمت ۶۴ بیتی علامت‌دار عدد صحیح یا عدد اعشاری ۶۴ بیتی برای ذخیره‌سازی آن مناسب است.

Video

این شی نشان‌دهنده یک فایل ویدیویی است.

فیلدنوعتوضیحات
file_idStringشناسه این فایل که می‌توان آن‌ را جهت دانلود یا استفاده مجدد از فایل به کار برد.
file_unique_idStringشناسه منحصربه‌فرد این فایل که فرض می‌شود، در طول زمان و برای بازوهای مختلف یکسان است. نمی‌توان این شناسه را برای دانلود یا استفاده مجدد از فایل به کار برد.
widthIntegerپهنای ویدیو
heightIntegerارتفاع ویدیو
durationIntegerمدت زمان ویدیو به ثانیه
file_nameStringاختیاری. نام اصلی فایل است.
mime_typeStringاختیاری. نوع MIME فایل
file_sizeIntegerاختیاری. حجم فایل با واحد بایت. می‌تواند بیشتر از ۲۳۱ باشد و برخی زبان‌های برنامه‌نویسی ممکن است در تفسیر آن با مشکل روبه‌رو شوند. اما این فیلد حداکثر ۵۲ بیت با ارزش اهمیت دارد و فرمت ۶۴ بیتی علامت‌دار عدد صحیح یا عدد اعشاری ۶۴ بیتی برای ذخیره‌سازی آن مناسب است.

Voice

این شی نشان‌دهنده یک پیام صوتی است.

فیلدنوعتوضیحات
file_idstringشناسه این فایل که می‌توان در جهت دانلود یا استفاده مجدد از فایل به کار برد.
file_unique_idstringشناسه منحصربه‌فرد این فایل که فرض می‌شود، در طول زمان و برای بازوهای مختلف یکسان است. نمی‌توان این شناسه را برای دانلود یا استفاده مجدد از فایل به کار برد.

Contact

این شی نشان‌دهنده یک مخاطب ذخیره شده توسط است.

فیلدنوعتوضیحات
phone_numberstringشماره تماس مخاطب
first_namestringنام کوچک مخاطب
last_namestringاختیاری. نام خانوادگی مخاطب
user_idIntegerاختیاری. شناسه کاربری مخاطب در بله. این شناسه دقیقا ۳۲بیت با ارزش دارد

Location

این شی نشان‌دهنده یک نقطه روی نقشه است.

فیلدنوعتوضیحات
longitudeFloatطول جغرافیایی
latitudeFloatعرض جغرافیایی

File

این شی نشان‌دهنده یک فایل آماده دانلود است. این فایل را می‌توان از طریق لینک https://tapi.bale.ai/file/bot<token>/<file_path (opens in a new tab) دانلود کرد.

فیلدنوعتوضیحات
file_idstringشناسه این فایل که می‌توان برای دانلود یا استفاده مجدد از فایل به کار برد
file_unique_idstringشناسه منحصربه‌فرد این فایل که فرض می‌شود در طول زمان و برای بازوهای مختلف یکسان است. نمی‌توان آن را برای دانلود یا استفاده مجدد از فایل به کار برد.
file_sizeIntegerاختیاری. حجم فایل با واحد بایت. می‌تواند بیشتر از ۲۳۱ باشد و برخی زبان‌های برنامه‌نویسی ممکن است در تفسیر آن با مشکل روبه‌رو شوند. اما این فیلد حداکثر ۵۲ بیت با ارزش اهمیت دارد و فرمت ۶۴ بیتی علامت‌دار عدد صحیح یا عدد اعشاری ۶۴ بیتی برای ذخیره‌سازی آن مناسب است.
file_pathstringاختیاری. مسیر فایل. از آدرس [https://tapi.bale.ai/file/bot<token>/<file_path (opens in a new tab)] برای دریافت فایل استفاده کنید.

ReplyKeyboardMarkup

این شی نشان‌دهنده یک صفحه‌کلید سفارشی با دکمه‌هایی برای ارسال پاسخ است.

فیلدنوعتوضیحات
keyboardآرایه‌ای از آرایه KeyboardButtonآرایه‌ای از ردیفی از دکمه‌ها که هر ردیف با یک آرایه از اشیای KeyboardButton نمایش داده می‌شود. .

KeyboardButton

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

فیلدنوعتوضیحات
textstringمتن دکمه. اگر هیچ یک از فیلدهای اختیاری استفاده نشوند، در صورت فشردن دکمه، این فیلد به صورت یک پیام ارسال خواهد شد.
request_contactBooleanاختیاری. اگر مقدار آن True‌ باشد، در صورت فشردن دکمه، شماره تماس کاربر به صورت یک مخاطب ارسال خواهد شد.
request_locationBooleanاختیاری. اگر مقدار آن True باشد، در صورت فشردن دکمه، موقعیت فعلی کاربر ارسال خواهد شد. (در نسخه تحت وب).

InlineKeyboardButton

یک دکمه از صفحه‌کلید inline را نشان می‌دهد. تنها می توانید از یکی از فیلدهای اختیاری استفاده کنید.

فیلدنوعتوضیحات
textstringمتن برچسب روی دکمه
urlstringاختیاری. آدرسی که با فشردن دکمه باید باز شود.
callback_datastringاختیاری. داده‌هایی که باید در یک درخواست فراخوانی برای بازو پس از فشردن دکمه ارسال شوند، بین ۱ تا ۶۴ بایت

CallbackQuery

این شی نشان‌دهنده‌ی یک فراخوان برگشتی ورودی از یک دکمه در یک صفحه‌کلید inline است. اگر دکمه‌ای که مبدا درخواست است به یک پیام ارسال‌شده توسط بازو پیوست شود، فیلد message وجود خواهد داشت. اگر دکمه به یک پیام ارسال‌شده از طریق بازو پیوست شده باشد، فیلد iniline_message_id وجود خواهد داشت.

فیلدنوعتوضیحات
idstringشناسه منحصربه‌فرد این درخواست
fromUserارسال‌کننده
messageMessageاختیاری. پیامی که دکمه به آن پیوست شده است. توجه داشته باشید که برای پیام‌های خیلی قدیمی، محتوای پیام و تاریخ آن در دسترس نخواهد بود.
datastringاختیاری. داده‌های مرتبط با دکمه. توجه داشته باشید که امکان دارد پیام، هیچ دکمه‌ای با این داده‌ها نداشته باشد.

ChatPhoto

این شی نشان‌دهنده یک تصویر گفتگو است.

فیلدنوعتوضیحات
small_file_idstringشناسه فایل برای تصویر کوچک گفتگو (۱۶۰×۱۶۰). این شناسه را فقط برای دانلود تصویر و فقط تا زمانی می‌توان استفاده کرد که تصویر مورد نظر تغییر نکرده باشد.
small_file_unique_idstringشناسه منحصربه‌فرد برای تصویر کوچک گفتگو (۱۶۰×۱۶۰)، که در طول زمان و برای بازوهای مختلف یکسان است. نمی‌توان آن را برای دانلود یا استفاده مجدد از فایل به کار برد.
big_file_idstringشناسه فایل برای تصویر بزرگ گفتگو (۶۴۰×۶۴۰). این شناسه را می‌توان برای دانلود تصویر و فقط تا زمانی استفاده کرد که تصویر تغییر نکرده باشد.
big_file_unique_idstringشناسه منحصربه‌فرد برای تصویر بزرگ گفتگو (۶۴۰×۶۴۰)، که در طول زمان و برای بازوهای مختلف یکسان است. نمی‌توان آن را برای دانلود یا استفاده مجدد از فایل به کار برد.

InputMedia

این شی محتوای پیام رسانه‌ای که باید ارسال گردد را مشخص می‌کند و باید یکی از موارد زیر باشد:

  • InputMediaAnimation

  • InputMediaDocument

  • InputMediaAudio

  • InputMediaPhoto

  • InputMediaVideo

InputMediaPhoto

نشان‌دهنده یک تصویر برای ارسال است.

فیلدنوعتوضیحات
typestringباید photo باشد.
mediastringفایلی که باید ارسال شود و ۳ حالت میتواند داشته باشد ۱) file_id را قرار دهید تا یک فایل که در سرورهای بله وجود دارد، ارسال شود (پیشنهادی) ۲) یک HTTP URL وارد کنید تا آن فایل از اینترنت دریافت شود ۳) عبارت “<attach://file_attach_name>” را وارد کنید تا یک فایل جدید با استفاده از multipart/form-data با نام <file_attach_name> آپلود شود.
captionstringاختیاری. زیرنویس تصویری که باید ارسال شود، بین ۰ تا ۱۰۲۴ کاراکتر

InputMediaVideo

نشان‌دهنده یک ویدیو برای ارسال است.

فیلدنوعتوضیحات
typestringباید video باشد.
mediastringفایلی که باید ارسال شود و ۳ حالت میتواند داشته باشد۱) یک file_id را قرار دهید وارد کنید تا یک فایل که در سرورهای بله وجود دارد، ارسال شود (پیشنهادی) ۲) یک HTTP URL وارد کنید تا آن یک فایل را از اینترنت دریافت شود. ۳) عبارت “<attach://file_attach_name>” را وارد کنید تا یک فایل جدید با استفاده از multipart/form-data با نام <file_attach_name> آپلود شود.
thumbnailInputFile یا stringاختیاری. thumbnail فایلی که ارسال می‌شود؛ اگر تولید thumbnail برای ویدیو در سمت سرور پشتیبانی شود، می‌توان آن را نادیده گرفت. thumbnail باید با فرمت JPEG و حجم آن کمتر از ۲۰۰ کیلوبایت باشد. پهنا و ارتفاع thumbnail نباید بیشتر از ۳۲۰ باشد. اگر ویدیو با استفاده از multipart/form-data آپلود نشده باشد، نادیده گرفته می‌شود. thumbnailها را نمی‌توان مجدداً استفاده کرد و آن‌ها را فقط می‌توان به صورت یک فایل جدید آپلود کرد، بنابراین اگر thumbnail با استفاده از multipart/form-data با نام <file_attach_name> آپلود شده باشد، می‌توانید عبارت “<attach://<file_attach_name>” را وارد کنید.
captionstringاختیاری. زیرنویس ویدیویی که باید ارسال شود، بین ۰ تا ۱۰۲۴ کاراکتر
widthIntegerاختیاری. پهنای تصویر ویدیو
heightIntegerاختیاری. ارتفاع تصویر ویدیو
durationIntegerاختیاری. مدت زمان ویدیو (در واحد ثانیه)

InputMediaAnimation

نشان‌دهنده یک فایل انیمیشن است (ویدیو GIF یا H.264/MPEG-4 AVC بدون صدا) برای ارسال است.

فیلدنوعتوضیحات
typestringباید animation باشد.
mediastringفایلی که باید ارسال شود و ۳ حالت میتواند داشته باشد. ۱)یک file_id را وارد کنید تا یک فایل که در سرورهای بله وجود دارد، ارسال شود (پیشنهادی)، ۲) یک HTTP URL وارد کنید تا آن یک فایل را از اینترنت دریافت شود ۳) یا عبارت “<attach://file_attach_name>” را وارد کنید تا یک فایل جدید را با استفاده از multipart/form-data با نام <file_attach_name> آپلود شود کنید.
thumbnailInputFile یا stringاختیاری. thumbnail فایلی که ارسال شده است؛ اگر تولید تامبنیل برای فایل در سمت سرور پشتیبانی شود، می‌توان آن را نادیده گرفت. تامبنیل باید با فرمت JPEG و حجم آن کمتر از ۲۰۰ کیلوبایت باشد. پهنا و ارتفاع تامبنیل نباید بیشتر از ۳۲۰ باشد. اگر فایل با استفاده از multipart/form-data آپلود نشده باشد، نادیده گرفته می‌شود. thumbnail ها را نمی‌توان مجدداً استفاده کرد و آن‌ها را فقط می‌توان به صورت یک فایل جدید آپلود کرد، بنابراین اگر thumbnail با استفاده از multipart/form-data با نام <file_attach_name> آپلود شده باشد، می‌توانید عبارت “<attach://<file_attach_name>” را وارد کنید.
captionstringاختیاری. زیرنویس انیمیشنی که باید ارسال شود، بین ۰ تا ۱۰۲۴ کاراکتر
widthIntegerاختیاری. پهنای تصویر انیمیشن
heightIntegerاختیاری. ارتفاع تصویر انیمیشن
durationIntegerاختیاری. مدت زمان انیمیشن (با واحد ثانیه)

InputMediaAudio

نشان‌دهنده یک فایل صوتی برای ارسال است. این فایل به صورت یک موسیقی در نظر گرفته می‌شود.

فیلدنوعتوضیحات
typestringباید audio باشد.
mediastringفایلی که باید ارسال شود و ۳ حالت میتواند داشته باشد. ۱)یک file_id را وارد کنید تا یک فایل که در سرورهای بله وجود دارد، ارسال شود (پیشنهادی)، ۲) یک HTTP URL وارد کنید تا آن یک فایل را از اینترنت دریافت شود ۳) یا عبارت “<attach://file_attach_name>” را وارد کنید تا یک فایل جدید را با استفاده از multipart/form-data با نام <file_attach_name> آپلود شود کنید.
thumbnailInputFile یا stringاختیاری. thumbnail فایلی که ارسال شده است؛ اگر تولید thumbnail برای فایل در سمت سرور پشتیبانی شود، می‌توان آن را نادیده گرفت. تامبنیل باید با فرمت JPEG و حجم آن کمتر از ۲۰۰ کیلوبایت باشد. پهنا و ارتفاع تامبنیل نباید بیشتر از ۳۲۰ باشد. اگر فایل با استفاده از multipart/form-data آپلود نشده باشد، نادیده گرفته می‌شود. تامبنیل‌ها را نمی‌توان مجدداً استفاده کرد و آن‌ها را فقط می‌توان به صورت یک فایل جدید آپلود کرد، بنابراین اگر thumbnail با استفاده از multipart/form-data با نام <file_attach_name> آپلود شده باشد، می‌توانید عبارت “<attach://<file_attach_name>” را وارد کنید.
captionstringاختیاری. زیرنویس فایل صوتی که باید ارسال شود، بین ۰ تا ۱۰۲۴ کاراکتر
durationIntegerاختیاری. مدت زمان فایل صوتی (در واحد ثانیه)
titlestringاختیاری. عنوان فایل صوتی

InputMediaDocument

نشان‌دهنده یک فایل برای ارسال است.

فیلدنوعتوضیحات
typestringباید document باشد.
mediastringفایلی که باید ارسال شود و ۳ حالت میتواند داشته باشد. ۱)یک file_id را وارد کنید تا یک فایل که در سرورهای بله وجود دارد، ارسال شود (پیشنهادی)، ۲) یک HTTP URL وارد کنید تا آن یک فایل را از اینترنت دریافت شود ۳) یا عبارت “<attach://file_attach_name>” را وارد کنید تا یک فایل جدید را با استفاده از multipart/form-data با نام <file_attach_name> آپلود شود کنید.
thumbnailInputFile یا stringاختیاری. thumbnail فایلی که ارسال شده است؛ اگر تولید thumbnail برای فایل در سمت سرور پشتیبانی شود، می‌توان آن را نادیده گرفت. تامبنیل باید با فرمت JPEG و حجم آن کمتر از ۲۰۰ کیلوبایت باشد. پهنا و ارتفاع تامبنیل نباید بیشتر از ۳۲۰ باشد. اگر فایل با استفاده از multipart/form-data آپلود نشده باشد، نادیده گرفته می‌شود. تامبنیل‌ها را نمی‌توان مجدداً استفاده کرد و آن‌ها را فقط می‌توان به صورت یک فایل جدید آپلود کرد، بنابراین اگر thumbnail با استفاده از multipart/form-data با نام <file_attach_name> آپلود شده باشد، می‌توانید عبارت “<attach://<file_attach_name>” را وارد کنید.
captionstringاختیاری. زیرنویس سندی که باید ارسال شود، بین ۰ تا ۱۰۲۴ کاراکتر

InputFile

این شی نشان‌دهنده محتوای یک فایل است که آپلود می‌شود. باید با استفاده از multipart/form-data به روش معمول و مشابه با آپلود فایل‌ها از طریق مرورگر ارسال شود.

ارسال فایل ها

سه روش برای ارسال فایل‌ها وجود دارد (تصاویر، استیکرها، فایل صوتی، رسانه‌ها و غیره):

۱- اگر فایل در حال حاضر در سرورهای بله ذخیره شده باشد، نیازی به آپلود مجدد آن نخواهد بود. هر شی فایل یک فیلد file_id دارد، این file_id را به عنوان یک پارامتر به جای بارگذاری کردن، وارد کنید. برای ارسال فایل‌ها از این طریق هیچ محدودیتی وجود ندارد.

۲- HTTP URL فایلی که باید ارسال شود ارسال کنید. بله فایل را دانلود و ارسال خواهد کرد. حداکثر اندازه ممکن برای تصاویر ۵ مگابایت است و ۲۰ مگابایت برای دیگر انواع محتوا.

۳- فایل را با استفاده از multipart/form-data به روش معمول و مشابه با آپلود از طریق مرورگر، با متد POST ارسال کنید. حداکثر اندازه‌ ممکن برای تصاویر ۱۰ مگابایت است و برای فایل‌های دیگر ۵۰ مگابایت.

ارسال با استفاده از file_id

  • تغییر نوع فایل در زمان ارسال مجدد آن از طریق file_id وجود ندارد. یعنی یک ویدیو را نمی‌توان به صورت یک تصویر و یک تصویر را نمی‌توان به صورت یک سند ارسال کرد.

  • امکان ارسال مجدد thumbnail ها وجود ندارد.

  • ارسال مجدد یک تصویر با استفاده از file_id تمام اندازه‌های آن تصویر را ارسال خواهد کرد.

  • file_id برای هر بازوی مجزا منحصربه‌فرد است و نمی‌توان آن را از یک بازو به بازوی دیگر انتقال داد.

  • file_id به صورت یکتا برای شناسایی یک فایل به کار می‌رود، اما یک فایل می‌تواند چندین file_id صحیح حتی برای همان بازو داشته باشد.

Sending by URL

  • در زمان ارسال از طریق URL، فایل باید دارای MIME صحیح باشد (برای مثال audio/mpeg برای sendAudio).

  • در sendDocument، ارسال با استفاده از URL فقط برای فایل‌های GIF، PDF و ZIP کار خواهد کرد.

  • برای استفاده از sendVoice، فایل باید از نوع audio/ogg باشد و حجم آن بیشتر از ۱ مگابایت نباشد. پیام‌های صوتی با حجم ۱ تا ۲۰ مگابایت به صورت فایل ارسال خواهند شد.

  • تنظیمات دیگر باید کار کند ولی هیچ تضمینی برای آن وجود ندارد.

متدهای موجود

نام متدهای موجود در API بازو، هیچ حساسیتی نسبت به حروف بزرگ و کوچک ندارند و متدهای GET‌ و POST پشتیبانی می‌شوند. برای ارسال پارامترها در درخواست‌های API بازو، چهار روش وجود دارد:

  • ارسال در URL درخواست (query string)

  • application/x-www-form-urlencoded

  • application/json

  • multipart/form-data

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

getme

یک متد ساده برای تست توکن احراز هویت بازو است. این متد به هیچ پارامتری نیاز ندارد و اطلاعات پایه بازو را به شکل یک شی User بر می‌گرداند.

logout

از این متد برای خروج از سرورِ ابریِ API بازو قبل از اجرای بازو در محیط تست استفاده کنید و به هیچ پارامتری نیاز ندارد. باید قبل از اجرای بازو در محیط تستی، از آن خارج شوید. در غیر این صورت، هیچ تضمینی وجود ندارد که بازو آپدیت‌ها را دریافت کند. بعد از یک فراخوان موفق، بلافاصله می‌توانید از طریق محیط تستی وارد شوید، اما به مدت ۱۰ دقیقه نمیتوانید وارد سرورِ ابریِ API‌ بازو شوید. در صورت اجرای موفقیت‌آمیز، خروجی آن True است.

close

از این متد به منظور بستن بازو قبل از انتقال آن از یک سرور لوکال یا محیط تستی به سرور دیگر استفاده کنید. باید قبل از فراخوانی این متد، وب‌هوک را حذف کنید تا مطمئن شوید که بازو بعد از راه‌اندازی مجدد سرور، بار دیگر اجرا نخواهد شد.

sendMessage

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

پارامترنوعالزامتوضیحات
chat_idString یا Integerالزامیشناسه منحصربه‌فرد گفتگو هدف یا نام‌ کاربری کانال (با فرمت @channelusername)
textstringالزامیمتن پیامی که باید ارسال شود، بین ۱ تا ۴۰۹۶ کاراکتر بعد از
reply_to_message_idIntegerشناسه‌ی پیام اصلی اگر که پیام یک پاسخ باشد.
reply_markupInlineKeyboardMarkup یا ReplyKeyboardMarkup یا ReplyKeyboardRemoveامکانات اضافه رابط کاربری بازو. یک شی JSON-serialized است که میتواند برای یک صفحه‌کلید inline یا ReplyMarkup و یا دستورالعمل‌هایی برای حذف صفحه‌کلید پاسخ باشد.

Formatting options

برای برجسته نوشتن کافی است متن را بین دو ستاره قرار دهید. توجه کنید که باید قبل از ستارۀ اول و بعد از ستارۀ دوم یک فاصله (اسپیس) بگذارید.

برای کج یا ایتالیک نوشتن کافی است عبارت را بین دو زیرخط (آندرلاین_) قرار بدهید. از این ویژگی می‌توان برای تأکید بر بخشی از متن یا جلب کردن توجه مخاطب به عبارتی خاص استفاده کرد. توجه کنید که باید قبل از زیرخط اول و بعد از زیرخط دوم یک فاصله (اسپیس) بگذارید.

برای ساخت لینک باید متن را بین دو کروشه بنویسید و آدرس لینک را بلافاصله (بدون اِسپِیس) داخل دو پرانتز بگذارید. از این ویژگی می‌توان برای ارجاع مخاطب به مطلبی دیگر در بله یا هر سایت دیگری استفاده کرد.

به این شکل: [متن]‌(آدرس‌لینک)

نمایش آنی از دیگر امکانات پیام‌رسان بله است که می‌توان به کمک آن، توضیحاتی به متن اصلی اضافه کرد. برای این کار کافی است متن را بین دو کروشه بگذارید و سه ‌```‌ قبل و بعد از توضیح تکمیل‌کننده قرار بدهید.

به این شکل: ```‌[متن]‌توضیحات‌```

forwardMessage

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

پارامترنوعالزامتوضیحات
chat_idString یا Integerالزامیشناسه منحصربه‌فرد گفتگوی هدف یا شناسه کانال هدف (با فرمت @channelusername)
from_chat_idInteger یا Stringالزامیشناسه منحصربه‌فرد گفتگویی که پیام اصلی در آن‌جا ارسال شده است (یا نام کاربری کانال با فرمت @channelusername)
message_idIntegerالزامیشناسه پیام در گفتگوی مشخص‌شده در from_chat_id

copyMessage

از این متد برای کپی کردن انواع پیام‌ها استفاده کنید. پیام‌های سرویس بله و پیام‌های رسید پرداخت قابل کپی شدن نیستند. این روش مشابه روش forwardMessage است، اما پیام کپی شده لینکی به پیام اصلی ندارد. در صورت موفقیت، MessageId پیام ارسال شده را برمی گرداند.

پارامترنوعالزامتوضیحات
chat_idString یا Integerالزامیشناسه منحصربه‌فرد گفتگوی هدف یا شناسه کانال هدف (با فرمت @channelusername)
from_chat_idInteger یا Stringالزامیشناسه منحصربه‌فرد گفتگویی که پیام اصلی در آن‌جا ارسال شده است (یا نام کاربری کانال با فرمت @channelusername)
message_idIntegerالزامیشناسه پیام در گفتگوی مشخص‌شده در from_chat_id

sendPhoto

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

پارامترنوعالزامتوضیحات
chat_idString یا Integerالزامیشناسه منحصربه‌فرد گفتگو هدف یا نام‌ کاربری کانال هدف (با فرمت @channelusername)
from_chat_idInteger یا Stringالزامیشناسه منحصربه‌فرد گفتگوی که پیام اصلی در آن‌جا ارسال شده است (یا نام کاربری کانال با فرمت @channelusername)
photoInputFile یا Stringالزامیتصویری که باید ارسال شود. یک file_id را به صورت رشته وارد کنید تا یک تصویر که در سرورهای بله وجود دارد، ارسال شود (پیشنهادی) یا یک HTTP URL به صورت رشته وارد کنید تا بله یک تصویر را از اینترنت دریافت و ارسال کند و یا یک تصویر جدید را با استفاده از multipart/form-data آپلود کنید.
captionStringاختیاریزیرنویس تصویر (در زمان ارسال مجدد تصاویر با استفاده از file_id نیز قابل استفاده است)، بین ۰ تا ۱۰۲۴ کاراکتر
reply_to_message_idIntegerاختیاریID پیام اصلی، در صورتی که پیام یک پاسخ باشد.
reply_markupInlineKeyboardMarkup یا ReplyKeyboardMarkup یا ReplyKeyboardRemoveاختیاریامکانات اضافه رابط کاربری بازو. یک شی JSON-serialized است که میتواند برای یک صفحه‌کلید inline یا ReplyMarkup و یا دستورالعمل‌هایی برای حذف صفحه‌کلید پاسخ باشد.

sendAudio

اگر می‌خواهید کلاینت‌های بله این فایل‌ها را در پخش کننده موسیقی نمایش دهند، از این متد برای ارسال فایل‌های صوتی استفاده کنید. فایل صوتی باید با فرمت .MP3 یا .M4A باشد. در صورت اجرای موفق، پیام ارسال‌شده برگردانده می‌شود. بازوهای فعلی مي‌توانند فایل‌های صوتی با اندازه‌های تا ۵۰ مگابایت را ارسال کنند. این محدودیت احتمال‌ دارد در آینده عوض شود.

برای ارسال پیام‌های صوتی، از متد sendVoice استفاده کنید.

پارامترنوعالزامتوضیحات
chat_idString یا Integerالزامیشناسه منحصربه‌فرد گفتگو هدف یا نام‌ کاربری کانال هدف (با فرمت @channelusername)
audioInputFile یا Stringالزامیفایل صوتی که باید ارسال شود. یک file_id را به صورت رشته وارد کنید تا یک فایل صوتی که در سرورهای بله وجود دارد، ارسال شود (پیشنهادی) یا یک HTTP URL به صورت رشته وارد کنید تا بله یک فایل صوتی را از اینترنت دریافت و ارسال کند و یا یک فایل صوتی جدید را با استفاده از multipart/form-data آپلود کنید.
captionStringاختیاریزیرنویس فایل صوتی، بین ۰ تا ۱۰۲۴ کاراکتر
reply_to_message_idIntegerاختیاریID پیام اصلی، در صورتی که پیام یک پاسخ باشد.
reply_markupInlineKeyboardMarkup یا ReplyKeyboardMarkup یا ReplyKeyboardRemoveاختیاریامکانات اضافه رابط کاربری بازو. یک شی JSON-serialized است که میتواند برای یک صفحه‌کلید inline یا ReplyMarkup و یا دستورالعمل‌هایی برای حذف صفحه‌کلید پاسخ باشد.

sendDocument

این متد به منظور ارسال فایل‌های عمومی استفاده می‌شود. در صورت اجرای موفق، پیام ارسال‌شده برگردانده می‌شود. در حال حاضر، بازوها می‌توانند هر نوع فایلی را با حداکثر اندازه ۵۰ مگابایت ارسال کنند. این محدودیت ممکن است در آینده تغییر کند.

پارامترنوعالزامتوضیحات
chat_idString یا Integerالزامیشناسه منحصربه‌فرد گفتگو هدف یا نام‌ کاربری کانال هدف (با فرمت @channelusername)
documentInputFile یا Stringالزامیفایلی که باید ارسال شود. یک file_id را به صورت رشته وارد کنید تا فایلی که در سرورهای بله وجود دارد، ارسال شود (پیشنهادی) یا یک HTTP URL به صورت رشته وارد کنید تا بله فایل را از اینترنت دریافت و ارسال کند و یا فایل جدیدی را با استفاده از multipart/form-data آپلود کنید.
captionStringاختیاریزیرنویس سند (در زمان ارسال مجدد اسناد از طریق file_id نیز قابل استفاده است)، بین ۰ تا ۱۰۲۴ کاراکتر
reply_to_message_idIntegerاختیاریID پیام اصلی، در صورتی که پیام یک پاسخ باشد.
reply_markupInlineKeyboardMarkup یا ReplyKeyboardMarkup یا ReplyKeyboardRemoveاختیاریامکانات اضافه رابط کاربری بازو. یک شی JSON-serialized است که میتواند برای یک صفحه‌کلید inline یا ReplyMarkup و یا دستورالعمل‌هایی برای حذف صفحه‌کلید پاسخ باشد.

sendVideo

این متد جهت ارسال فایل‌های ویدیویی استفاده می‌شوند، کلاینت‌های بله از ویدیوهای MPEG4 پشتیبانی می‌کنند (فرمت‌های دیگر نیز به صورت Document قابل ارسال هستند). در صورت اجرای موفق، خروجی پیام ارسال‌شده خواهد بود. بازوها در حال حاضر می‌توانند فایل‌های ویدیویی با حداکثر اندازه ۵۰ مگابایت را ارسال کنند. این محدودیت ممکن است در آینده دستخوش تغییر شود.

پارامترنوعالزامتوضیحات
chat_idString یا Integerالزامیشناسه منحصربه‌فرد گفتگو هدف یا نام‌ کاربری کانال هدف (با فرمت @channelusername)
videoInputFile یا Stringالزامیویدیویی که باید ارسال شود. یک file_id را به صورت رشته وارد کنید تا ویدیویی که در سرورهای بله وجود دارد، ارسال شود (پیشنهادی) یا یک HTTP URL به صورت رشته وارد کنید تا ویدیویی را از اینترنت دریافت کنید و یا ویدیویی جدید را با استفاده از multipart/form-data آپلود کنید.
captionStringاختیاریزیرنویس ویدیو (می‌توان در زمان ارسال مجدد ویدیوها از طریق file_id استفاده کرد)، بین ۰ تا ۱۰۲۴ کاراکتر بعد از تجزیه موجودیت‌ها
reply_to_message_idIntegerاختیاریID پیام اصلی، در صورتی که پیام یک پاسخ باشد.
reply_markupInlineKeyboardMarkup یا ReplyKeyboardMarkup یا ReplyKeyboardRemoveاختیاریامکانات اضافه رابط کاربری بازو. یک شی JSON-serialized است که میتواند برای یک صفحه‌کلید inline یا ReplyMarkup و یا دستورالعمل‌هایی برای حذف صفحه‌کلید پاسخ باشد.

sendAnimation

این متد به منظور ارسال فایل‌های انیمیشن (ویدیو GIF یا H.264/MPEG-4 AVC بدون صدا) استفاده می‌شود. در صورت موفقیت، خروجی آن پیام ارسال‌شده است. بازوها در حال حاضر می‌توانند فایل‌های انیمیشنی با حداکثر حجم ۵۰ مگابایت را ارسال کنند. این محدودیت می‌تواند در آینده تغییر پیدا کند.

پارامترنوعالزامتوضیحات
chat_idString یا Integerالزامیشناسه منحصربه‌فرد گفتگو هدف یا نام‌ کاربری کانال هدف (با فرمت @channelusername)
animationInputFile یا Stringالزامیانیمیشنی که باید ارسال شود. یک file_id را به صورت رشته وارد کنید تا انیمیشنی که در سرورهای بله وجود دارد، ارسال شود (پیشنهادی) یا یک HTTP URL به صورت رشته وارد کنید تا بله آن انیمیشن را از اینترنت دریافت و ارسال کند و یا انیمیشن جدیدی را با استفاده از multipart/form-data آپلود کنید.
reply_to_message_idIntegerاختیاریID پیام اصلی، در صورتی که پیام یک پاسخ باشد.
reply_markupInlineKeyboardMarkup یا ReplyKeyboardMarkup یا ReplyKeyboardRemoveاختیاریامکانات اضافه رابط کاربری بازو. یک شی JSON-serialized است که میتواند برای یک صفحه‌کلید inline یا ReplyMarkup و یا دستورالعمل‌هایی برای حذف صفحه‌کلید پاسخ باشد.

sendVoice

اگر می‌خواهید کلاینت‌های بله فایل را به صورت یک پیام صوتی نمایش دهند، از این روش برای ارسال فایل‌های صوتی استفاده کنید. . در صورت اجرای موفق، خروجی پیام ارسال‌شده است. در حال حاضر، بازوها می‌توانند پیام‌های صوتی با حداکثر حجم ۵۰ مگابایت را ارسال کنند. این محدودیت می‌تواند در آینده دچار تغییر شود.

پارامترنوعالزامتوضیحات
chat_idString یا Integerالزامیشناسه منحصربه‌فرد گفتگو هدف یا نام‌ کاربری کانال هدف (با فرمت @channelusername)
voiceInputFile یا Stringالزامیفایل صوتی که باید ارسال شود. یک file_id را به صورت رشته وارد کنید تا یک فایل صوتی که در سرورهای بله وجود دارد، ارسال شود (پیشنهادی) یا یک HTTP URL به صورت رشته وارد کنید تا بله یک فایل صوتی را از اینترنت دریافت و ارسال کند و یا یک فایل صوتی جدید را با استفاده از multipart/form-data آپلود کنید.
captionStringاختیاریزیرنویس پیام صوتی، بین ۰ تا ۱۰۲۴ کاراکتر بعد از تجزیه موجودیت‌ها
reply_to_message_idIntegerاختیاریID پیام اصلی، در صورتی که پیام یک پاسخ باشد.
reply_markupInlineKeyboardMarkup یا ReplyKeyboardMarkup یا ReplyKeyboardRemoveاختیاریامکانات اضافه رابط کاربری بازو. یک شی JSON-serialized است که میتواند برای یک صفحه‌کلید inline یا ReplyMarkup و یا دستورالعمل‌هایی برای حذف صفحه‌کلید پاسخ باشد.

sendMediaGroup

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

پارامترنوعالزامتوضیحات
chat_idString یا Integerالزامیشناسه منحصربه‌فرد گفتگو هدف یا نام‌ کاربری کانال هدف (با فرمت @channelusername)
mediaآرایه‌ای از InputMediaAudio، InputMediaDocument، InputMediaPhoto و InputMediaVideoالزامییک آرایه JSON-serialized شامل پیام‌هایی که باید ارسال شوند،
reply_to_message_idIntegerاختیاریID پیام اصلی، در صورتی که پیام یک پاسخ باشد.

sendLocation

این متد به منظور ارسال نقطه‌ای از نقشه استفاده می‌شود. در صورت اجرای موفق، پیام ارسال‌شده به عنوان خروجی برگردانده می‌شود.

پارامترنوعالزامتوضیحات
chat_idString یا Integerالزامیشناسه منحصربه‌فرد گفتگو هدف یا نام‌ کاربری کانال هدف (با فرمت @channelusername)
latitudeFloatالزامیعرض جغرافیایی موقعیت مکانی
longitudeFloatالزامطول جغرافیایی موقعیت مکانی
horizontal_accuracyFloatاختیاریشعاع عدم قطعیت برای یک نقطه مکانی، با واحد متر اندازه‌گیری می‌شود و عددی بین ۰ تا ۱۵۰۰ است.
reply_to_message_idIntegerاختیاریID پیام اصلی، در صورتی که پیام یک پاسخ باشد.
reply_markupInlineKeyboardMarkup یا ReplyKeyboardMarkup یا ReplyKeyboardRemoveاختیاریامکانات اضافه رابط کاربری بازو. یک شی JSON-serialized است که میتواند برای یک صفحه‌کلید inline یا ReplyMarkup و یا دستورالعمل‌هایی برای حذف صفحه‌کلید پاسخ باشد.

sendContact

این متد به منظور ارسال یک مخاطب تلفن استفاده می‌شود. در صورت اجرای موفقیت‌آمیز، پیام ارسال‌شده به عنوان خروجی برگردانده می‌شود.

پارامترنوعالزامتوضیحات
chat_idString یا Integerالزامیشناسه منحصربه‌فرد گفتگو هدف یا نام‌ کاربری کانال هدف (با فرمت @channelusername)
phone_numberIntegerالزامیشماره تماس مخاطب
first_nameIntegerالزامینام کوچک مخاطب
last_nameIntegerاختیاریاختیاری. نام خانوادگی مخاطب
reply_to_message_idIntegerاختیاریID پیام اصلی، در صورتی که پیام یک پاسخ باشد.
reply_markupInlineKeyboardMarkup یا ReplyKeyboardMarkup یا ReplyKeyboardRemoveاختیاریامکانات اضافه رابط کاربری بازو. یک شی JSON-serialized است که میتواند برای یک صفحه‌کلید inline یا ReplyMarkup و یا دستورالعمل‌هایی برای حذف صفحه‌کلید پاسخ باشد.

getFile

این متد برای دریافت اطلاعات پایه‌ی یک فایل و آماده‌سازی آن برای دانلود استفاده می‌شود. در حال حاضر، بازوها می‌توانند فایل‌هایی با حداکثر حجم ۲۰ مگابایت را دانلود کنند. در صورت اجرای موفق، یک شی File بر می‌گرداند. سپس، فایل را می‌توان از طریق لینک <https://tapi.bale.ai/file/bot<token>/<file_path (opens in a new tab) دانلود کرد، که در این لینک، <file_path> از پاسخ دریافت می‌شود. صحت لینک برای یک ساعت تضمین شده است. زمانی که لینک منقضی شود، یک لینک جدید را می‌توان با فراخوانی مجدد این متد دریافت کرد.

پارامترنوعالزامتوضیحات
file_idStringالزامیشناسه فایلی که باید اطلاعات آن دریافت شود.

banChatMember

این متد برای مسدود کردن کاربر در یک گروه یا یک کانال استفاده می‌شود. در مورد گروه‌ها و کانال‌ها، کاربر نخواهد توانست از طریق لینک‌های دعوت به گفتگو برگردد، مگر اینکه در ابتدا از حالت مسدود خارج شود. برای اینکه این متد کار کند، بازو باید مدیر گفتگو باشد و حقوق و اختیارات مربوط به مدیران را داشته باشد. در صورت اجرای موفق، مقدار True‌ را بر می‌گرداند.

پارامترنوعالزامتوضیحات
chat_idString یا Integerالزامیشناسه منحصربه‌فرد گروه هدف یا نام کاربری کانال هدف (با فرمت @channelusername)
user_idIntegerالزامیشناسه منحصربه‌فرد کاربر هدف

unbanChatMember

این متد جهت خارج‌ کردن یک کاربر مسدودشده از حالت مسدود در یک گروه یا کانال استفاده می‌شوند. کاربر به صورت خودکار به گروه یا کانال بر نخواهد گشت، اما امکان پیوستن به گروه از طریق لینک دعوت را دارد. برای این منظور، بازو باید مدیر گفتگو باشد. به طور پیش‌فرض، این متد تضمین می‌کند که بعد از فراخوانی، کاربر عضوی از گفتگو نیست، اما می‌تواند به آن بپیوندد. بنابراین، اگر کاربر عضوی از گفتگو باشد، از محیط گفتگو نیز حذف خواهد شد. اگر نمی‌خواهید این اتفاق بیافتد، از پارامتر only_if_banned استفاده کنید. در صورت اجرای موفق، خروجی True است.

پارامترنوعالزامتوضیحات
chat_idString یا Integerالزامیشناسه منحصربه‌فرد گروه هدف یا نام کاربری گروه یا کانال هدف (با فرمت @channelusername)
user_idIntegerالزامیشناسه منحصربه‌فرد کاربر هدف
only_if_bannedBooleanاختیاریاگر کاربر مسدود نشده است، کاری انجام دهد.

promoteChatMember

این متد به منظور ارتقا یا تنزل یک کاربر در یک گروه یا کانال استفاده می‌شود. برای این کار، بازو باید مدیر گفتگو باشد و حقوق و اختیارات مدیریتی متناسب داشته باشد. جهت تنزل یک کاربر، مقدار تمام پارامترهای Boolean را False قرار دهید. در صورت اجرای موفق، مقدار True را بر می‌گرداند.

پارامترنوعالزامتوضیحات
chat_idString یا Integerالزامیشناسه منحصربه‌فرد گفتگو هدف یا نام کاربری کانال هدف (با فرمت @channelusername)
user_idIntegerالزامیشناسه منحصربه‌فرد کاربر هدف
can_change_infoBooleanاختیاریاگر میخواهید ادمین توانایی تغییر اطلاعات چت را داشته باشد True را ارسال کنید
can_post_messagesBooleanاختیاریتوانایی ارسال پست توسط کاربر
can_edit_messagesBooleanاختیاریتوانایی ویرایش پیام های چت
can_delete_messagesBooleanاختیاریتوانایی حذف پیام های چت
can_manage_video_chatsBooleanاختیاریتوانایی مدیریت تماس تصویری
can_invite_usersBooleanاختیاریتوانایی دعوت کاربر
can_restrict_membersBooleanاختیاریتوانایی محدود کردن کاربران

setChatPhoto

این متد به منظور تنظیم یک تصویر پروفایل جدید برای گفتگو استفاده می‌شود. تصاویر برای گفتگو‌های خصوصی قابل تغییر نیستند. برای این منظور، بازو باید مدیر گفتگو باشد و باید حقوق و اختیارات مدیریتی متناسب داشته باشد. در صورت اجرای موفق، مقدار True را بر می‌گرداند.

پارامترنوعالزامتوضیحات
chat_idString یا Integerالزامیشناسه منحصربه‌فرد برای گفتگو هدف یا نام‌ کاربری کانال هدف (با فرمت @channelusername)
photoInputFileالزامیتصویر گفتگو جدید که با استفاده از multipart/form-data آپلود شده است.

leaveChat

این متد برای بازو به منظور ترک یک گروه، گروه یا کانال استفاده می‌شود. در صورت اجرای موفق، خروجی آن مقدار True است.

پارامترنوعالزامتوضیحات
chat_idString یا Integerالزامیشناسه منحصربه‌فرد برای گفتگو هدف یا نام‌ کاربری کانال هدف (با فرمت @channelusername)

getChat

این متد به منظور دریافت اطلاعات به‌روز در مورد گفتگو (نام فعلی کاربر برای مکالمات یک به یک، نام کاربری فعلی یک کاربر، گروه یا کانال). در صورت اجرای موفق، یک شی Chat (opens in a new tab) بر می‌گرداند.

پارامترنوعالزامتوضیحات
chat_idString یا Integerالزامیشناسه منحصربه‌فرد برای گفتگو هدف یا نام‌ کاربری کانال هدف (با فرمت @channelusername)

getChatMembersCount

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

پارامترنوعالزامتوضیحات
chat_idString یا Integerالزامیشناسه منحصربه‌فرد برای گفتگو هدف یا نام‌ کاربری کانال هدف (با فرمت @channelusername)

pinChatMessage

با استفاده از این متد میتوانید یک پیام را به پیام های پین شده اضافه کنید. اگرچت خصوصی نباشد بازو باید ادمین باشد و دسترسی can_pin_messages را داشته باشد

پارامترنوعالزامتوضیحات
chat_idString یا Integerالزامیشناسه منحصربه‌فرد برای گفتگو هدف یا نام‌ کاربری کانال هدف (با فرمت @channelusername)
message_idIntegerالزامیشناسه منحصر به فرد پیام

unPinChatMessage

با استفاده از این متد میتوانید یک پیام را از پیام های پین شده حذف کنید. اگرچت خصوصی نباشد بازو باید ادمین باشد و دسترسی can_pin_messages را داشته باشد

پارامترنوعالزامتوضیحات
chat_idString یا Integerالزامیشناسه منحصربه‌فرد برای گفتگو هدف یا نام‌ کاربری کانال هدف (با فرمت @channelusername)
message_idIntegerالزامیشناسه منحصر به فرد پیام

unpinAllChatMessages

با استفاده از این متد میتوانید همه پیام ها را حذف کنید. اگرچت خصوصی نباشد بازو باید ادمین باشد و دسترسی can_pin_messages را داشته باشد

پارامترنوعالزامتوضیحات
chat_idString یا Integerالزامیشناسه منحصربه‌فرد برای گفتگو هدف یا نام‌ کاربری کانال هدف (با فرمت @channelusername)

setChatTitle

با استفاده از این متد میتوان عنوان چت را تغییر داد. این متد در چت های خصوصی کاربردی ندارد.

پارامترنوعالزامتوضیحات
chat_idString یا Integerالزامیشناسه منحصربه‌فرد برای گفتگو هدف یا نام‌ کاربری کانال هدف (با فرمت @channelusername)
titleStringالزامیعنوان جدید گروه

setChatDescription

با استفاده از این متد میتوان توضیحات یک گروه یا یک کانال را تغییر داد. بازو در این گفتگوها باید دسترسی مربوط را داشته باشد.

پارامترنوعالزامتوضیحات
chat_idString یا Integerالزامیشناسه منحصربه‌فرد برای گفتگو هدف یا نام‌ کاربری کانال هدف (با فرمت @channelusername)
descriptionStringالزامیتوضیحات جدید

deleteChatPhoto

با استفاده از این متد میتوان عکس چت را حذف کرد. این متد در چت های خصوصی کاربردی ندارد. بازو برای استفاده باید دسترسی مربوط را داشته باشد.

پارامترنوعالزامتوضیحات
chat_idString یا Integerالزامیشناسه منحصربه‌فرد برای گفتگو هدف یا نام‌ کاربری کانال هدف (با فرمت @channelusername)

createChatInviteLink

با استفاده از این متد می توان برای گروه لینک جدید ایجاد کرد.

پارامترنوعالزامتوضیحات
chat_idString یا Integerالزامیشناسه منحصربه‌فرد برای گفتگو هدف یا نام‌ کاربری کانال هدف (با فرمت @channelusername)

revokeChatInviteLink

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

پارامترنوعالزامتوضیحات
chat_idString یا Integerالزامیشناسه منحصربه‌فرد برای گفتگو هدف یا نام‌ کاربری کانال هدف (با فرمت @channelusername)
invite_linkStringالزامیلینک عضویت

exportChatInviteLink

.با استفاده از این متد بازو می تواند برای یک چت لینک عضویت جدید ایجاد کند در صورتی که قبلا ایجاد شده باشد ابطال و جدید ساخته می شود

پارامترنوعالزامتوضیحات
chat_idString یا Integerالزامیشناسه منحصربه‌فرد برای گفتگو هدف یا نام‌ کاربری کانال هدف (با فرمت @channelusername)

به روز رسانی پیام‌ها

متدهای زیر به شما اجازه می‌دهند که یک پیام موجود در تاریخچه پیام را به جای ارسال یک پیام جدید، به وسیله یک اقدام تغییر دهید. این متد برای پیام‌هایی با صفحه‌کلیدهای inline مفید است و از طرف دیگر، به کاهش درهم‌ریختگی در مکالمات با بازوهای گفتگو معمولی کمک می‌کند.

توجه داشته باشید که در حال حاضر، فقط امکان ویرایش پیام‌های بدون reply_markup یا صفحه‌کلید‌های inline وجود دارد.

editMessageText

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

پارامترنوعالزامتوضیحات
chat_idString یا Integerاختیاریدر صورتی نیاز است که inline_message_id مشخص نشده باشد. شناسه منحصربه‌فرد برای گفتگو هدف یا نام کاربری کانال هدف (با فرمت @channelusername)
message_idIntegerاختیاریدر صورتی نیاز است که inline_message_id مشخص نشده باشد. شناسه پیامی که باید ویرایش شود.
textStringالزامیمتن جدید پیام، بین ۱ تا ۴۰۹۶ کاراکتر بعد از تجزیه موجودیت‌ها
reply_markupInlineKeyboardMarkupاختیارییک شی JSON-serialized برای یک صفحه‌کلید inline

deleteMessage

این متد به منظور حذف یک پیام، از جمله پیام‌های سرویس، با محدودیت‌های زیر استفاده می‌شود:

- یک پیام فقط در صورتی قابل حذف است که کمتر از ۴۸ ساعت قبل ارسال شده باشد.

- بازوها می‌توانند پیام‌های خروجی را در گفتگو‌های خصوصی و گروه‌ها حذف کنند.

- بازوها می‌توانند پیام‌های ورودی را در گفتگو‌های خصوصی حذف کنند.

- اگر بازو مدیر یک گروه باشد، می‌تواند هر پیامی در گروه را حذف کند.

- اگر بازو دارای مجوز can_delete_messages در کانال باشد، می‌تواند هر پیامی را در آنجا حذف کند.

در صورت اجرای موفق، مقدار True‌ را بر می‌گرداند.

پارامترنوعالزامتوضیحات
chat_idString یا Integerالزامیشناسه منحصربه‌فرد برای گفتگو هدف یا نام کاربری کانال هدف (با فرمت @channelusername)
message_idIntegerالزامیشناسه پیامی که باید حذف شود.

استیکرها

متدها و اشیای زیر به بازوی شما اجازه می‌دهند که استیکرها و بسته‌های استیکر را مدیریت کنید.

Sticker

این شی نشان‌دهنده یک استیکر است.

فیلدنوعتوضیحات
file_idStringشناسه این فایل که می‌توان آن‌ را جهت دانلود یا استفاده مجدد از فایل به کار برد.
file_unique_idStringشناسه منحصربه‌فرد این فایل که فرض می‌شود، در طول زمان و برای بازوهای مختلف یکسان است. نمی‌توان این شناسه را برای دانلود یا استفاده مجدد از فایل به کار برد.
typeStringنوع استیکر که در حال حاضر یکی از انواع “regular” یا “mask” می‌تواند باشد.
widthIntegerپهنای استیکر
heightIntegerارتفاع استیکر
file_sizeIntegerاختیاری. اندازه فایل با واحد بایت

StickerSet

این شی نشان‌دهنده یک بسته‌ی استیکر است.

فیلدنوعتوضیحات
nameStringنام بسته‌ استیکر
titleStringعنوان بسته‌ استیکر
stickersآرایه‌ای از Stickerلیست تمام استیکرهای مجموعه
thumbnailPhotoSizeاختیاری. thumbnail بسته‌ استیکر با فرمت .WEBP، .TGS یا .WEBM

uploadStickerFile

این متد به منظور آپلود یک فایل برای استفاده در متدهای createNewStickerSet و addStickerToSet در آینده استفاده می‌شود (چندین بار می‌توان فایل را استفاده کرد). در صورت اجرای موفق، فایل آپلودشده را بر می‌گرداند.

پارامترنوعالزامتوضیحات
user_idIntegerالزامیشناسه کاربری مالک فایل استیکر
stickerInputFileالزامییک فایل به فرمت .WEBP، .PNG، .TGS یا .WEBM.

createNewStickerSet

این متد به منظور ایجاد یک بسته‌ی استیکر جدید با مالکیت کاربر ایجاد کننده استفاده می‌شود. بازو می‌تواند بسته‌ی استیکر ایجادشده را ویرایش کند. در صورت اجرای موفق، مقدار True را بر می‌گرداند.

پارامترنوعالزامتوضیحات
user_idIntegerالزامیشناسه کاربری مالک مجموعه استیکر تولیدشده
nameStringالزامینام کوتاه مجموعه استیکر که در URL های /t.me/addstickers استفاده می‌شود (برای مثال animals). این نام می‌تواند شامل حروف انگلیسی، اعداد یا "_" باشد. باید با یک حرف شروع شود و نمی‌تواند شامل چند خط underscore باشد و باید در پایان "by_bot_username_" قرار گیرد. bot_username نسبت به حروف بزرگ و کوچک حساس است. بین ۱ تا ۶۴ کاراکتر
titleStringالزامیعنوان بسته‌ی استیکر، بین ۱ تا ۶۴ کاراکتر
stickerآرایه‌ای از InputStickerالزامییک لیست JSON-serialized شامل ۱ تا ۵۰ استیکر که باید به بسته‌ی استیکر اضافه شوند.

addStickerToSet

این متد به منظور اضافه‌کردن یک استیکر جدید به یک بسته‌ی ایجادشده توسط بازو استفاده می‌شود. فرمت استیکر اضافه‌شده باید با فرمت دیگر استیکرها در مجموعه مطابقت داشته باشد. مجموعه‌های استیکر ایموجی می‌توانند تا ۲۰۰ استیکر داشته باشند. مجموعه‌های استیکر ویدیویی می‌توانند تا ۵۰ استیکر داشته باشند. مجموعه‌های استیکر معمولی می‌توانند تا ۱۲۰ استیکر داشته باشند. در صورت اجرای موفق، مقدار True را بر می‌گرداند.

پارامترنوعالزامتوضیحات
user_idIntegerالزامیشناسه کاربری مالک بسته‌ی استیکر
nameStringالزامینام بسته‌ی استیکر
stickerInputStickerالزامییک شی JSON-serialized با اطلاعاتی در مورد استیکر اضافه‌شده. اگر دقیقاً همان استیکر به بسته اضافه شده باشد، بسته‌ی استیکر تغییر نخواهد کرد.

پرداخت

بازوهای بله می توانند درخواست های پول را به عنوان صورتحساب خرید برای کاربران ارسال کنند و پرداخت های کاربران را دریافت کنند.

متد sendInvoice به منظور ارسال درخواست پول استفاده می‌شود. در صورت اجرای موفق، پیام ارسال‌شده را بر می‌گرداند.

پارامترنوعالزامتوضیحات
chat_idString یا Integerالزامیشناسه منحصربه‌فرد گفتگو هدف یا نام‌ کاربری کانال هدف (با فرمت @channelusername)
titleStringالزامینام محصول، بین ۱ تا ۳۲ کاراکتر
descriptionStringالزامیتوصیف محصول، بین ۱ تا ۲۵۵ کاراکتر
payloadStringالزامیpayload صورتحساب تعریف‌شده توسط بازو، بین ۱ تا ۱۲۸ بایت. این فیلد برای کاربر نمایش داده نمی‌شود. از آن برای فرآیندهای داخلی خود استفاده کنید.این مقدار پس از پرداخت موفق در آپدیت SuccessfulPayment بازگشت داده میشود و میتوان با استفاده از این مقدار، درخواست های پول را متمایز کرد.
provider_tokenStringالزامیشماره کارت پشت درخواست پول
pricesآرایه‌ای از LabeledPriceالزامیتفکیک قیمت‌ها، یک لیست JSON-serialized از محصولات سفارش شامل عنوان کالا و قیمت محصول است که مجموع آنها به عنوان مبلغ نهایی در نظر گرفته می شود.
photo_urlStringاختیاریURL تصویر محصول برای صورتحساب. یک تصویر از کالا را می توانید به عنوان تصویر درخواست پول ارسال کنید.وقتی افراد، چیزی را که برای آن هزینه می‌کنند، ببینند، حس بهتری خواهند داشت.
reply_to_message_idIntegerاختیاریشناسه پیام اصلی که بر روی آن پاسخ داده شده است.
reply_markupInlineKeyboardMarkupاختیاریامکانات اضافه رابط کاربری بازو. یک شی JSON-serialized است که میتواند برای یک صفحه‌کلید inline یا ReplyMarkup و یا دستورالعمل‌هایی برای حذف صفحه‌کلید پاسخ باشد.