مستندات بازوی بله

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

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

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

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

تمامی درخواست‌های مربوط به 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_id	Integer	شناسه منحصربه‌فرد آپدیت. شناسه‌های آپدیت از صفر آغاز شده و به ترتیب افزایش می‌یابند. این ID مخصوصا زمانی به کار می‌آید که از وب‌هوک استفاده کنید، زیرا به شما اجازه می‌دهد که آپدیت‌های تکراری را نادیده گرفته و یا اگر از ترتیب خارج شده ‌باشند، دنباله آپدیت درست را بازیابی کنید.
message	Message	اختیاری. پیام‌ دریافتی جدید از هر نوعی – متن، تصویر، استیکر و غیره
edited_message	Message	اختیاری. نسخه ویرایش شده پیامی که در گذشته برای بازو ارسال شده است.
callback_query	CallbackQuery	اختیاری. callback query دریافتی جدید.هنگامی که بر روی دکمه های inline پیام ها کلیک می شود، یک آپدیت دارای این فیلد ارسال می شود. فیلد data در شئ CallBackQuery برابر با مقداری است که هنگام تعریف دکمه مشخص می شود.

getUpdates

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

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

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

setWebhook

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

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

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

getWebhookInfo

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

WebhookInfo

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

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

انواع موجود

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

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

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

User

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

فیلد	نوع	توضیحات
id	Integer	اختیاری. می‌تواند بیشتر از ۲^۳۱ باشد و برخی زبان‌های برنامه‌نویسی ممکن است در تفسیر آن با مشکل روبه‌رو شوند. اما این فیلد حداکثر ۵۲ بیت با ارزش اهمیت دارد و فرمت ۶۴ بیتی علامت‌دار عدد صحیح یا عدد اعشاری ۶۴ بیتی برای ذخیره‌سازی آن مناسب است.
is_bot	Boolean	اگر کاربر، یک بازو باشد، مقدار آن True است.
first_name	string	نام کوچک کاربر یا بازو
last_name	string	اختیاری. نام خانوادگی کاربر یا بازو
username	string	اختیاری. نام کاربری کاربر یا بازو
language_code	string	اختیاری. برچسب زبانی IETF برای زبان کاربر

Chat

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

فیلد	نوع	توضیحات
id	Integer	شناسه یکتای چت. می‌تواند بیشتر از ۲^۳۱ باشد و برخی زبان‌های برنامه‌نویسی ممکن است در تفسیر آن با مشکل روبه‌رو شوند. اما این فیلد حداکثر ۵۲ بیت با ارزش اهمیت دارد و فرمت ۶۴ بیتی علامت‌دار عدد صحیح یا عدد اعشاری ۶۴ بیتی برای ذخیره‌سازی آن مناسب است.
type	string	نوع گفتگو که می‌تواند یکی از موارد "private”، “group” یا “channel” باشد.
title	string	اختیاری. عنوان گفتگو‌های داخل گروه‌ها یا کانال‌ها
username	string	اختیاری. نام کاربری برای گفتگو‌های خصوصی یا کانال‌ها در صورت وجود
first_name	string	اختیاری. نام کوچک طرف دیگر در یک گفتگوی خصوصی
last_name	string	اختیاری. نام خانوادگی طرف دیگر در یک گفتگوی خصوصی
photo	ChatPhoto	اختیاری. تصویر گفتگو. فقط از طریق getChat بدست می‌آید.

Message

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

فیلد	نوع	توضیحات
message_id	Integer	شناسه منحصربه‌فرد پیام در داخل این گفتگو
from	User	اختیاری. کاربر ارسال‌کننده‌ی پیام. برای پیام‌هایی که در کانال ارسال می‌شوند، مقدار آن خالی است.
date	Integer	تاریخی که پیام ارسال شده است (در قالب زمان یونیکس)
chat	Chat	اطلاعات گفتگویی که پیام به آن تعلق دارد.
forward_from	User	اختیاری. برای پیام‌های باز ارسال شده که ارسال‌کننده‌ی پیام اصلی را نشان می‌دهد
forward_from_chat	Chat	اختیاری. برای پیام های باز ارسال شده که اطلاعات مربوط به گفتگوی اصلی پیام را نشان می‌دهد و در کانال‌ها, از طرف مدیران ناشناس است
forward_from_message_id	Integer	اختیاری. شناسه پیام اصلی در کانال، برای پیام‌های باز ارسال شده از کانال‌ها
forward_date	Integer	اختیاری. برای پیام های باز ارسال شده , تاریخی که پیام اصلی در آن زمان ارسال شده است (در قالب زمان یونیکس)
reply_to_message	Message	اختیاری. پیام اصلی که روی آن پاسخی داده شده است. توجه داشته باشید که حتی اگر خود شی Message در این فیلد، یک پاسخ به پیام باشد، این فیلد مقدار دهی نمی‌شود.
edite_date	Integer	اختیاری. تاریخ آخرین باری که پیام ویرایش شده است (در قالب زمان یونیکس)
text	String	اختیاری. متن واقعی پیام با فرمت UTF-8 برای پیام‌های متنی
animation	Animation	اختیاری برای پیام‌های که تصویر متحرک دارند این فیلد پر می شود و اطلاعاتی در مورد انیمیشن می‌دهد. برای سازگاری عقب‌رو، زمانی که این فیلد تنظیم شود، فیلد document نیز تنظیم خواهد شد.
audio	Audio	اختیاریبرای پیام‌هایی که به صورت فایل صوتی هستند این فیلد با اطلاعات فایل مقدار دهی می شود.
document	Document	اختیاری. برای پیام‌هایی که به صورت فایل عمومی هستند، اطلاعاتی در مورد فایل می‌دهد.
photo	آرایه‌ای از PhotoSize	اختیاری. برای پیام‌هایی که به صورت تصویر هستند، اندازه‌های موجود برای تصویر را می‌دهد.
sticker	Sticker	اختیاری. برای پیام‌هایی که به صورت استیکر هستند، اطلاعاتی در مورد استیکر می‌دهد.
video	Video	اختیاری. برای پیام‌هایی که به صورت ویدیو هستند، اطلاعاتی در مورد ویدیو می‌دهد.
voice	Voice	اختیاری. برای پیام‌های صوتی، اطلاعاتی در مورد فایل می‌دهد.
caption	String	اختیاری. توضیحات مربوط به انیمیشن، فایل صوتی، سند، تصویر، ویدیو یا پیام صوتی
contact	Contact	اختیاری. در صورتی که پیام یک مخاطب به اشتراک‌گذاشته‌شده باشد، اطلاعاتی در مورد مخاطب می‌دهد.
location	Location	اختیاری. اگر پیام یک موقعیت به اشتراک‌گذاشته‌شده باشد، اطلاعاتی در مورد این موقعیت می‌دهد.
new_chat_members	آرایه‌ای از User	اختیاری.اطلاعاتی در مورد اعضای جدیدی که به گروه اضافه شده‌اند می دهد (خود بازو می‌تواند یکی از این اعضا باشد)
left_chat_member	User	اختیاری. عضوی که از گروه حذف یا خارج شده است و اطلاعاتی در مورد آن (این عضو می‌تواند خود بازو باشد)
invoice	Invoice	اختیاری. در صورتی که پیام یک صورتحساب برای یک عملیات پرداخت باشد، اطلاعاتی در مورد صورتحساب می‌دهد.
successful_payment	SuccessfulPayment	اختیاری. در صورتی که پیام یک پرداخت موفق باشد ، اطلاعاتی در مورد پرداخت می‌دهد.
reply_markup	InlineKeyboardMarkup	اختیاری. صفحه‌کلید inline که به یک پیام پیوست شده است. کلیدهای login_url به عنوان کلیدهای url معمولی نشان داده می‌شوند.

MessageId

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

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

PhotoSize

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

فیلد	نوع	توضیحات
file_id	String	شناسه این فایل که می‌توان آن‌ را جهت دانلود یا استفاده مجدد از فایل به کار برد.
file_unique_id	String	شناسه منحصربه‌فرد این فایل است که در طول زمان و برای بازوهای مختلف یکسان است. نمی‌توان این شناسه را برای دانلود یا استفاده مجدد از فایل به کار برد.
width	Integer	پهنای تصویر
height	Integer	ارتفاع تصویر
file_size	Integer	اختیاری. حجم فایل با واحد بایت

Animation

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

فیلد	نوع	توضیحات
file_id	String	شناسه این فایل که می‌توان آن‌ را جهت دانلود یا استفاده مجدد از فایل به کار برد.
file_unique_id	String	شناسه منحصربه‌فرد این فایل که فرض می‌شود، در طول زمان و برای بازوهای مختلف یکسان است. نمی‌توان این شناسه را برای دانلود یا استفاده مجدد از فایل به کار برد.
width	Integer	پهنای تصویر ویدیو
height	Integer	ارتفاع تصویر ویدیو
duration	Integer	مدت زمان ویدیو به ثانیه
thumbnail	PhotoSize	اختیاری. thumbnail انیمیشن
file_name	String	اختیاری. نام اصلی انیمیشن
mime_type	String	اختیاری. نوع MIME فایل
file_size	Integer	اختیاری. حجم فایل با واحد بایت. می‌تواند بیشتر از ۲^۳۱ باشد و برخی زبان‌های برنامه‌نویسی ممکن است در تفسیر آن با مشکل روبه‌رو شوند. اما این فیلد حداکثر ۵۲ بیت با ارزش اهمیت دارد و فرمت ۶۴ بیتی علامت‌دار عدد صحیح یا عدد اعشاری ۶۴ بیتی برای ذخیره‌سازی آن مناسب است.

Audio

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

فیلد	نوع	توضیحات
file_id	string	شناسه این فایل که می‌توان آن‌ را جهت دانلود یا استفاده مجدد از فایل به کار برد.
file_unique_id	string	شناسه منحصربه‌فرد این فایل که فرض می‌شود، در طول زمان و برای بازوهای مختلف یکسان است. نمی‌توان این شناسه را برای دانلود یا استفاده مجدد از فایل به کار برد.
duration	Integer	مدت زمان فایل صوتی به ثانیه.
title	string	اختیاری. عنوان فایل صوتی
file_name	string	اختیاری. نام اصلی فایل
mime_type	string	اختیاری. نوع MIME فایل
file_size	Integer	اختیاری. حجم فایل با واحد بایت. می‌تواند بیشتر از ۲^۳۱ باشد و برخی زبان‌های برنامه‌نویسی ممکن است در تفسیر آن با مشکل روبه‌رو شوند. اما این فیلد حداکثر ۵۲ بیت با ارزش اهمیت دارد و فرمت ۶۴ بیتی علامت‌دار عدد صحیح یا عدد اعشاری ۶۴ بیتی برای ذخیره‌سازی آن مناسب است.

Document

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

فیلد	نوع	توضیحات
file_id	String	شناسه این فایل که می‌توان آن‌ را جهت دانلود یا استفاده مجدد از فایل به کار برد.
file_unique_id	String	شناسه منحصربه‌فرد این فایل که فرض می‌شود، در طول زمان و برای بازوهای مختلف یکسان است. نمی‌توان این شناسه را برای دانلود یا استفاده مجدد از فایل به کار برد.
thumbnail	PhotoSize	اختیاری. thumbnail سند که توسط ارسال‌کننده تعریف شده است.
file_name	String	اختیاری. نام اصلی فایل
mime_type	String	اختیاری. نوع MIME فایل
file_size	Integer	اختیاری. حجم فایل با واحد بایت. می‌تواند بیشتر از ۲^۳۱ باشد و برخی زبان‌های برنامه‌نویسی ممکن است در تفسیر آن با مشکل روبه‌رو شوند. اما این فیلد حداکثر ۵۲ بیت با ارزش اهمیت دارد و فرمت ۶۴ بیتی علامت‌دار عدد صحیح یا عدد اعشاری ۶۴ بیتی برای ذخیره‌سازی آن مناسب است.

Video

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

فیلد	نوع	توضیحات
file_id	String	شناسه این فایل که می‌توان آن‌ را جهت دانلود یا استفاده مجدد از فایل به کار برد.
file_unique_id	String	شناسه منحصربه‌فرد این فایل که فرض می‌شود، در طول زمان و برای بازوهای مختلف یکسان است. نمی‌توان این شناسه را برای دانلود یا استفاده مجدد از فایل به کار برد.
width	Integer	پهنای ویدیو
height	Integer	ارتفاع ویدیو
duration	Integer	مدت زمان ویدیو به ثانیه
file_name	String	اختیاری. نام اصلی فایل است.
mime_type	String	اختیاری. نوع MIME فایل
file_size	Integer	اختیاری. حجم فایل با واحد بایت. می‌تواند بیشتر از ۲^۳۱ باشد و برخی زبان‌های برنامه‌نویسی ممکن است در تفسیر آن با مشکل روبه‌رو شوند. اما این فیلد حداکثر ۵۲ بیت با ارزش اهمیت دارد و فرمت ۶۴ بیتی علامت‌دار عدد صحیح یا عدد اعشاری ۶۴ بیتی برای ذخیره‌سازی آن مناسب است.

Voice

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

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

Contact

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

فیلد	نوع	توضیحات
phone_number	string	شماره تماس مخاطب
first_name	string	نام کوچک مخاطب
last_name	string	اختیاری. نام خانوادگی مخاطب
user_id	Integer	اختیاری. شناسه کاربری مخاطب در بله. این شناسه دقیقا ۳۲بیت با ارزش دارد

Location

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

فیلد	نوع	توضیحات
longitude	Float	طول جغرافیایی
latitude	Float	عرض جغرافیایی

File

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

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

ReplyKeyboardMarkup

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

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

KeyboardButton

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

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

InlineKeyboardButton

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

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

CallbackQuery

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


فیلد	نوع	توضیحات
id	string	شناسه منحصربه‌فرد این درخواست
from	User	ارسال‌کننده
message	Message	اختیاری. پیامی که دکمه به آن پیوست شده است. توجه داشته باشید که برای پیام‌های خیلی قدیمی، محتوای پیام و تاریخ آن در دسترس نخواهد بود.
data	string	اختیاری. داده‌های مرتبط با دکمه. توجه داشته باشید که امکان دارد پیام، هیچ دکمه‌ای با این داده‌ها نداشته باشد.

ChatPhoto

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

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

InputMedia

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

InputMediaAnimation
InputMediaDocument
InputMediaAudio
InputMediaPhoto
InputMediaVideo

InputMediaPhoto

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

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

InputMediaVideo

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

فیلد	نوع	توضیحات
type	string	باید video باشد.
media	string	فایلی که باید ارسال شود و ۳ حالت میتواند داشته باشد۱) یک file_id را قرار دهید وارد کنید تا یک فایل که در سرورهای بله وجود دارد، ارسال شود (پیشنهادی) ۲) یک HTTP URL وارد کنید تا آن یک فایل را از اینترنت دریافت شود. ۳) عبارت “<attach://file_attach_name>” را وارد کنید تا یک فایل جدید با استفاده از multipart/form-data با نام <file_attach_name> آپلود شود.
thumbnail	InputFile یا string	اختیاری. thumbnail فایلی که ارسال می‌شود؛ اگر تولید thumbnail برای ویدیو در سمت سرور پشتیبانی شود، می‌توان آن را نادیده گرفت. thumbnail باید با فرمت JPEG و حجم آن کمتر از ۲۰۰ کیلوبایت باشد. پهنا و ارتفاع thumbnail نباید بیشتر از ۳۲۰ باشد. اگر ویدیو با استفاده از multipart/form-data آپلود نشده باشد، نادیده گرفته می‌شود. thumbnailها را نمی‌توان مجدداً استفاده کرد و آن‌ها را فقط می‌توان به صورت یک فایل جدید آپلود کرد، بنابراین اگر thumbnail با استفاده از multipart/form-data با نام <file_attach_name> آپلود شده باشد، می‌توانید عبارت “<attach://<file_attach_name>” را وارد کنید.
caption	string	اختیاری. زیرنویس ویدیویی که باید ارسال شود، بین ۰ تا ۱۰۲۴ کاراکتر
width	Integer	اختیاری. پهنای تصویر ویدیو
height	Integer	اختیاری. ارتفاع تصویر ویدیو
duration	Integer	اختیاری. مدت زمان ویدیو (در واحد ثانیه)

InputMediaAnimation

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

فیلد	نوع	توضیحات
type	string	باید animation باشد.
media	string	فایلی که باید ارسال شود و ۳ حالت میتواند داشته باشد. ۱)یک file_id را وارد کنید تا یک فایل که در سرورهای بله وجود دارد، ارسال شود (پیشنهادی)، ۲) یک HTTP URL وارد کنید تا آن یک فایل را از اینترنت دریافت شود ۳) یا عبارت “<attach://file_attach_name>” را وارد کنید تا یک فایل جدید را با استفاده از multipart/form-data با نام <file_attach_name> آپلود شود کنید.
thumbnail	InputFile یا string	اختیاری. thumbnail فایلی که ارسال شده است؛ اگر تولید تامبنیل برای فایل در سمت سرور پشتیبانی شود، می‌توان آن را نادیده گرفت. تامبنیل باید با فرمت JPEG و حجم آن کمتر از ۲۰۰ کیلوبایت باشد. پهنا و ارتفاع تامبنیل نباید بیشتر از ۳۲۰ باشد. اگر فایل با استفاده از multipart/form-data آپلود نشده باشد، نادیده گرفته می‌شود. thumbnail ها را نمی‌توان مجدداً استفاده کرد و آن‌ها را فقط می‌توان به صورت یک فایل جدید آپلود کرد، بنابراین اگر thumbnail با استفاده از multipart/form-data با نام <file_attach_name> آپلود شده باشد، می‌توانید عبارت “<attach://<file_attach_name>” را وارد کنید.
caption	string	اختیاری. زیرنویس انیمیشنی که باید ارسال شود، بین ۰ تا ۱۰۲۴ کاراکتر
width	Integer	اختیاری. پهنای تصویر انیمیشن
height	Integer	اختیاری. ارتفاع تصویر انیمیشن
duration	Integer	اختیاری. مدت زمان انیمیشن (با واحد ثانیه)

InputMediaAudio

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

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

InputMediaDocument

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

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

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_id	String یا Integer	الزامی	شناسه منحصربه‌فرد گفتگو هدف یا نام‌ کاربری کانال (با فرمت @channelusername)
text	string	الزامی	متن پیامی که باید ارسال شود، بین ۱ تا ۴۰۹۶ کاراکتر بعد از
reply_to_message_id	Integer		شناسه‌ی پیام اصلی اگر که پیام یک پاسخ باشد.
reply_markup	InlineKeyboardMarkup یا ReplyKeyboardMarkup یا ReplyKeyboardRemove		امکانات اضافه رابط کاربری بازو. یک شی JSON-serialized است که میتواند برای یک صفحه‌کلید inline یا ReplyMarkup و یا دستورالعمل‌هایی برای حذف صفحه‌کلید پاسخ باشد.

Formatting options

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

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

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

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

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

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

forwardMessage

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

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

copyMessage

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

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

sendPhoto

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

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

sendAudio

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

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

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

sendDocument

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

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

sendVideo

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

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

sendAnimation

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

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

sendVoice

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

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

sendMediaGroup

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

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

sendLocation

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

پارامتر	نوع	الزام	توضیحات
chat_id	String یا Integer	الزامی	شناسه منحصربه‌فرد گفتگو هدف یا نام‌ کاربری کانال هدف (با فرمت @channelusername)
latitude	Float	الزامی	عرض جغرافیایی موقعیت مکانی
longitude	Float	الزام	طول جغرافیایی موقعیت مکانی
horizontal_accuracy	Float	اختیاری	شعاع عدم قطعیت برای یک نقطه مکانی، با واحد متر اندازه‌گیری می‌شود و عددی بین ۰ تا ۱۵۰۰ است.
reply_to_message_id	Integer	اختیاری	ID پیام اصلی، در صورتی که پیام یک پاسخ باشد.
reply_markup	InlineKeyboardMarkup یا ReplyKeyboardMarkup یا ReplyKeyboardRemove	اختیاری	امکانات اضافه رابط کاربری بازو. یک شی JSON-serialized است که میتواند برای یک صفحه‌کلید inline یا ReplyMarkup و یا دستورالعمل‌هایی برای حذف صفحه‌کلید پاسخ باشد.

sendContact

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

پارامتر	نوع	الزام	توضیحات
chat_id	String یا Integer	الزامی	شناسه منحصربه‌فرد گفتگو هدف یا نام‌ کاربری کانال هدف (با فرمت @channelusername)
phone_number	Integer	الزامی	شماره تماس مخاطب
first_name	Integer	الزامی	نام کوچک مخاطب
last_name	Integer	اختیاری	اختیاری. نام خانوادگی مخاطب
reply_to_message_id	Integer	اختیاری	ID پیام اصلی، در صورتی که پیام یک پاسخ باشد.
reply_markup	InlineKeyboardMarkup یا 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_id	String	الزامی	شناسه فایلی که باید اطلاعات آن دریافت شود.

banChatMember

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

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

unbanChatMember

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

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

promoteChatMember

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

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

setChatPhoto

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

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

leaveChat

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

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

getChat

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

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

getChatMemberCount

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

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

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

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

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

editMessageText

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

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

deleteMessage

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

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

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

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

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

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

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

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

استیکرها

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

Sticker

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

فیلد	نوع	توضیحات
file_id	String	شناسه این فایل که می‌توان آن‌ را جهت دانلود یا استفاده مجدد از فایل به کار برد.
file_unique_id	String	شناسه منحصربه‌فرد این فایل که فرض می‌شود، در طول زمان و برای بازوهای مختلف یکسان است. نمی‌توان این شناسه را برای دانلود یا استفاده مجدد از فایل به کار برد.
type	String	نوع استیکر که در حال حاضر یکی از انواع “regular” یا “mask” می‌تواند باشد.
width	Integer	پهنای استیکر
height	Integer	ارتفاع استیکر
file_size	Integer	اختیاری. اندازه فایل با واحد بایت

StickerSet

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

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

uploadStickerFile

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

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

createNewStickerSet

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

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

addStickerToSet

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

پارامتر	نوع	الزام	توضیحات
user_id	Integer	الزامی	شناسه کاربری مالک بسته‌ی استیکر
name	String	الزامی	نام بسته‌ی استیکر
sticker	InputSticker	الزامی	یک شی JSON-serialized با اطلاعاتی در مورد استیکر اضافه‌شده. اگر دقیقاً همان استیکر به بسته اضافه شده باشد، بسته‌ی استیکر تغییر نخواهد کرد.

پرداخت

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

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

پارامتر	نوع	الزام	توضیحات
chat_id	String یا Integer	الزامی	شناسه منحصربه‌فرد گفتگو هدف یا نام‌ کاربری کانال هدف (با فرمت @channelusername)
title	String	الزامی	نام محصول، بین ۱ تا ۳۲ کاراکتر
description	String	الزامی	توصیف محصول، بین ۱ تا ۲۵۵ کاراکتر
payload	String	الزامی	payload صورتحساب تعریف‌شده توسط بازو، بین ۱ تا ۱۲۸ بایت. این فیلد برای کاربر نمایش داده نمی‌شود. از آن برای فرآیندهای داخلی خود استفاده کنید.این مقدار پس از پرداخت موفق در آپدیت SuccessfulPayment بازگشت داده میشود و میتوان با استفاده از این مقدار، درخواست های پول را متمایز کرد.
provider_token	String	الزامی	شماره کارت پشت درخواست پول
prices	آرایه‌ای از LabeledPrice	الزامی	تفکیک قیمت‌ها، یک لیست JSON-serialized از محصولات سفارش شامل عنوان کالا و قیمت محصول است که مجموع آنها به عنوان مبلغ نهایی در نظر گرفته می شود.
photo_url	String	اختیاری	URL تصویر محصول برای صورتحساب. یک تصویر از کالا را می توانید به عنوان تصویر درخواست پول ارسال کنید.وقتی افراد، چیزی را که برای آن هزینه می‌کنند، ببینند، حس بهتری خواهند داشت.
reply_to_message_id	Integer	اختیاری	شناسه پیام اصلی که بر روی آن پاسخ داده شده است.
reply_markup	InlineKeyboardMarkup	اختیاری	امکانات اضافه رابط کاربری بازو. یک شی JSON-serialized است که میتواند برای یک صفحه‌کلید inline یا ReplyMarkup و یا دستورالعمل‌هایی برای حذف صفحه‌کلید پاسخ باشد.