Methods
BotClient
کلاس اصلی برای مدیریت ارتباط با API ربات بله. این کلاس وظیفه مدیریت ارتباط با API، ثبت هندلرها، مدیریت Middlewareها و دریافت آپدیتهای ربات را بر عهده دارد.
| پارامتر | نوع | توضیحات |
|---|---|---|
| token | str |
اجباری - توکن ربات برای برقراری ارتباط با API بله. |
| use_webhook | bool |
اختیاری - مشخص میکند ربات از Webhook استفاده کند یا Polling. مقدار پیشفرض False است. |
on_update
یک دکوراتور برای ثبت هندلرهای دریافت آپدیت. هر تابعی که با این دکوراتور ثبت شود، هنگام دریافت آپدیت و در صورت عبور از فیلترهای مشخصشده اجرا خواهد شد.
| پارامتر | نوع | توضیحات |
|---|---|---|
| *filter_func | - | اختیاری - یک یا چند فیلتر که قبل از اجرای هندلر بررسی میشوند. |
middleware
یک دکوراتور برای ثبت Middlewareهای ربات. Middlewareها قبل از اجرای هندلر اجرا میشوند و میتوانند عملیات موردنیاز را قبل و بعد از اجرای هندلر انجام دهند. برای ادامه روند پردازش، باید تابع call_next() فراخوانی شود.
| پارامتر | نوع | توضیحات |
|---|---|---|
| - | - | این متد پارامتر ورودی ندارد. |
نمونه استفاده
from gyron.bot import BotClient
import asyncio
app = BotClient('TOKEN')
@app.middleware()
async def middleware(update, call_next):
print('before handler')
await call_next()
print('after handler')
@app.on_update()
async def echo(update):
await app.reply(update.text)
asyncio.run(app.run())
get_updates
آپدیتهای جدید ربات را از طریق متد getUpdates از API بله دریافت میکند.
| پارامتر | نوع | توضیحات |
|---|---|---|
| offset | int |
اختیاری - شناسه اولین آپدیتی که باید دریافت شود. |
| limit | int |
اختیاری - حداکثر تعداد آپدیتهایی که در هر درخواست دریافت میشوند. |
| timeout | int |
اختیاری - مدت زمان انتظار سرور برای Long Polling (بر حسب ثانیه). |
| request_timeout | int |
اختیاری - حداکثر مدت زمان انتظار برای ارسال درخواست HTTP (بر حسب ثانیه). |
خروجی:
dict[str, Any]
دیکشنری شامل پاسخ API و لیست آپدیتهای دریافتشده.
send_message
یک پیام متنی را به چت یا کاربر موردنظر ارسال میکند. این متد از کیبوردهای معمولی و اینلاین نیز پشتیبانی میکند و امکان پاسخ دادن به یک پیام مشخص را فراهم میسازد.
| پارامتر | نوع | توضیحات |
|---|---|---|
| chat_id | Union[str, int] |
اجباری - شناسه یا آیدی چتی که پیام باید به آن ارسال شود. |
| text | str |
اجباری - متن پیام. |
| markup | Union[InlineKeypad, Keypad] |
اختیاری - کیبورد اینلاین یا معمولی که همراه پیام ارسال میشود. |
| reply_to_message_id | int |
اختیاری - شناسه پیامی که پیام جدید در پاسخ به آن ارسال میشود. |
خروجی:
MessageResponse
شیئی شامل اطلاعات پیام ارسالشده.
get_me
اطلاعات مربوط به ربات را از API دریافت میکند.
| پارامتر | نوع | توضیحات |
|---|---|---|
| - | - | این متد پارامتر ورودی ندارد. |
خروجی:
GetMeResponse
شیئی شامل اطلاعات ربات مانند شناسه، نام کاربری و سایر اطلاعات عمومی.
set_webhook
آدرس Webhook ربات را تنظیم میکند تا آپدیتها به آن ارسال شوند.
| پارامتر | نوع | توضیحات |
|---|---|---|
| url | str |
اجباری - آدرس Webhook که آپدیتهای ربات به آن ارسال خواهند شد. |
خروجی:
ApiResponse
یک شیء از نوع ApiResponse را برمیگرداند.
delete_webhook
Webhook تنظیمشده برای ربات را حذف میکند.
| پارامتر | نوع | توضیحات |
|---|---|---|
| - | - | این متد پارامتر ورودی ندارد. |
خروجی:
ApiResponse
یک شیء از نوع ApiResponse را برمیگرداند.
get_webhook_info
اطلاعات مربوط به Webhook فعلی ربات را دریافت میکند.
| پارامتر | نوع | توضیحات |
|---|---|---|
| - | - | این متد پارامتر ورودی ندارد. |
خروجی:
WebhookInfo
شیئی شامل اطلاعات Webhook فعلی مانند وضعیت، آدرس و سایر جزئیات مربوط به آن.
forward_message
یک پیام را از یک چت به چت دیگر فوروارد میکند.
| پارامتر | نوع | توضیحات |
|---|---|---|
| from_chat_id | Union[str, int] |
اجباری - شناسه چتی که پیام از آن فوروارد میشود. |
| chat_id | Union[str, int] |
اجباری - شناسه چتی که پیام به آن ارسال میشود. |
| message_id | int |
اجباری - شناسه پیام موردنظر برای فوروارد. |
خروجی:
MessageResponse
شیئی شامل اطلاعات پیام فورواردشده.
copy_message
یک نسخه از پیام را بدون نمایش برچسب فوروارد، در چت مقصد ارسال میکند.
| پارامتر | نوع | توضیحات |
|---|---|---|
| from_chat_id | Union[str, int] |
اجباری - شناسه چتی که پیام از آن کپی میشود. |
| chat_id | Union[str, int] |
اجباری - شناسه چتی که پیام در آن ارسال میشود. |
| message_id | int |
اجباری - شناسه پیام موردنظر برای کپی. |
خروجی:
MessageResponse
شیئی شامل اطلاعات پیام کپیشده.
reply
به پیام فعلی پاسخ میدهد و نیازی به مشخص کردن chat_id یا message_id نیست.
| پارامتر | نوع | توضیحات |
|---|---|---|
| text | str |
اجباری - متن پاسخ. |
| markup | Union[Keypad, InlineKeypad] |
اختیاری - کیبورد معمولی یا اینلاین که همراه پیام ارسال میشود. |
خروجی:
Union[MessageResponse, None]
شیئی شامل اطلاعات پیام ارسالشده.
send_photo
یک تصویر را به چت موردنظر ارسال میکند. تصویر میتواند از طریق شناسه فایل، آدرس اینترنتی یا فایل محلی ارسال شود.
| پارامتر | نوع | توضیحات |
|---|---|---|
| chat_id | Union[str, int] |
اجباری - شناسه چتی که تصویر به آن ارسال میشود. |
| file | str |
اجباری - شناسه فایل، آدرس اینترنتی یا مسیر فایل محلی. |
| from_chat_id | Union[str, int] |
اختیاری - شناسه چتی که فایل از آن کپی میشود. |
| caption | str |
اختیاری - متن توضیحی تصویر. |
| reply_to_message_id | int |
اختیاری - شناسه پیامی که تصویر در پاسخ به آن ارسال میشود. |
| markup | Union[InlineKeypad, Keypad] |
اختیاری - کیبورد معمولی یا اینلاین همراه پیام. |
| is_local_file | bool |
اختیاری - اگر True باشد، مقدار file بهعنوان مسیر فایل محلی در نظر گرفته میشود. مقدار پیشفرض False است. |
خروجی:
SendMediaResult
شیئی شامل اطلاعات تصویر ارسالشده.
send_audio
یک فایل صوتی را به چت موردنظر ارسال میکند. فایل میتواند از طریق شناسه فایل، آدرس اینترنتی یا فایل محلی ارسال شود.
| پارامتر | نوع | توضیحات |
|---|---|---|
| chat_id | Union[str, int] |
اجباری - شناسه چتی که فایل صوتی به آن ارسال میشود. |
| file | str |
اجباری - شناسه فایل، آدرس اینترنتی یا مسیر فایل محلی. |
| caption | str |
اختیاری - متن توضیحی فایل صوتی. |
| reply_to_message_id | int |
اختیاری - شناسه پیامی که فایل صوتی در پاسخ به آن ارسال میشود. |
| markup | Union[InlineKeypad, Keypad] |
اختیاری - کیبورد معمولی یا اینلاین همراه پیام. |
| is_local_file | bool |
اختیاری - اگر True باشد، مقدار file بهعنوان مسیر فایل محلی در نظر گرفته میشود. مقدار پیشفرض False است. |
خروجی:
SendMediaResult
شیئی شامل اطلاعات فایل صوتی ارسالشده.
send_document
یک فایل را به چت موردنظر ارسال میکند. فایل میتواند از طریق شناسه فایل، آدرس اینترنتی یا فایل محلی ارسال شود.
| پارامتر | نوع | توضیحات |
|---|---|---|
| chat_id | Union[str, int] |
اجباری - شناسه چتی که فایل به آن ارسال میشود. |
| file | str |
اجباری - شناسه فایل، آدرس اینترنتی یا مسیر فایل محلی. |
| caption | str |
اختیاری - متن توضیحی فایل. |
| reply_to_message_id | int |
اختیاری - شناسه پیامی که فایل در پاسخ به آن ارسال میشود. |
| markup | Union[InlineKeypad, Keypad] |
اختیاری - کیبورد معمولی یا اینلاین همراه پیام. |
| is_local_file | bool |
اختیاری - اگر True باشد، مقدار file بهعنوان مسیر فایل محلی در نظر گرفته میشود. مقدار پیشفرض False است. |
خروجی:
SendMediaResult
شیئی شامل اطلاعات فایل ارسالشده.
send_video
یک فایل ویدیویی را به چت موردنظر ارسال میکند. فایل میتواند از طریق شناسه فایل، آدرس اینترنتی یا فایل محلی ارسال شود.
| پارامتر | نوع | توضیحات |
|---|---|---|
| chat_id | Union[str, int] |
اجباری - شناسه چتی که ویدیو به آن ارسال میشود. |
| file | str |
اجباری - شناسه فایل، آدرس اینترنتی یا مسیر فایل محلی. |
| caption | str |
اختیاری - متن توضیحی ویدیو. |
| reply_to_message_id | int |
اختیاری - شناسه پیامی که ویدیو در پاسخ به آن ارسال میشود. |
| markup | Union[InlineKeypad, Keypad] |
اختیاری - کیبورد معمولی یا اینلاین همراه پیام. |
| is_local_file | bool |
اختیاری - اگر True باشد، مقدار file بهعنوان مسیر فایل محلی در نظر گرفته میشود. مقدار پیشفرض False است. |
خروجی:
SendMediaResult
شیئی شامل اطلاعات ویدیوی ارسالشده.
send_animation
یک فایل انیمیشن (GIF) را به چت موردنظر ارسال میکند. فایل میتواند از طریق شناسه فایل، آدرس اینترنتی یا فایل محلی ارسال شود.
| پارامتر | نوع | توضیحات |
|---|---|---|
| chat_id | Union[str, int] |
اجباری - شناسه چتی که انیمیشن به آن ارسال میشود. |
| file | str |
اجباری - شناسه فایل، آدرس اینترنتی یا مسیر فایل محلی. |
| caption | str |
اختیاری - متن توضیحی انیمیشن. |
| reply_to_message_id | int |
اختیاری - شناسه پیامی که انیمیشن در پاسخ به آن ارسال میشود. |
| markup | Union[InlineKeypad, Keypad] |
اختیاری - کیبورد معمولی یا اینلاین همراه پیام. |
| is_local_file | bool |
اختیاری - اگر True باشد، مقدار file بهعنوان مسیر فایل محلی در نظر گرفته میشود. مقدار پیشفرض False است. |
خروجی:
SendMediaResult
شیئی شامل اطلاعات انیمیشن ارسالشده.
send_voice
یک پیام صوتی (Voice) را به چت موردنظر ارسال میکند. فایل میتواند از طریق شناسه فایل، آدرس اینترنتی یا فایل محلی ارسال شود.
| پارامتر | نوع | توضیحات |
|---|---|---|
| chat_id | Union[str, int] |
اجباری - شناسه چتی که پیام صوتی به آن ارسال میشود. |
| file | str |
اجباری - شناسه فایل، آدرس اینترنتی یا مسیر فایل محلی. |
| caption | str |
اختیاری - متن توضیحی پیام صوتی. |
| reply_to_message_id | int |
اختیاری - شناسه پیامی که پیام صوتی در پاسخ به آن ارسال میشود. |
| markup | Union[InlineKeypad, Keypad] |
اختیاری - کیبورد معمولی یا اینلاین همراه پیام. |
| is_local_file | bool |
اختیاری - اگر True باشد، مقدار file بهعنوان مسیر فایل محلی در نظر گرفته میشود. مقدار پیشفرض False است. |
خروجی:
SendMediaResult
شیئی شامل اطلاعات پیام صوتی ارسالشده.
send_media_group
چند فایل رسانهای را بهصورت یک آلبوم در یک پیام برای چت موردنظر ارسال میکند.
| پارامتر | نوع | توضیحات |
|---|---|---|
| chat_id | Union[str, int] |
اجباری - شناسه چتی که آلبوم در آن ارسال میشود. |
| media | List[InputMediaPhoto] |
اجباری - لیستی از فایلهای رسانهای که باید بهصورت گروهی ارسال شوند. |
| reply_to_message_id | int |
اختیاری - شناسه پیامی که آلبوم در پاسخ به آن ارسال میشود. |
خروجی:
SendMediaGroupResult
شیئی شامل اطلاعات آلبوم رسانهای ارسالشده.
send_location
موقعیت جغرافیایی را برای چت موردنظر ارسال میکند.
| پارامتر | نوع | توضیحات |
|---|---|---|
| chat_id | Union[str, int] |
اجباری - شناسه چتی که موقعیت مکانی به آن ارسال میشود. |
| latitude | float |
اجباری - عرض جغرافیایی موقعیت. |
| longitude | float |
اجباری - طول جغرافیایی موقعیت. |
| horizontal_accuracy | float |
اختیاری - میزان دقت موقعیت جغرافیایی بر حسب متر. |
| reply_to_message_id | int |
اختیاری - شناسه پیامی که موقعیت مکانی در پاسخ به آن ارسال میشود. |
| markup | Union[InlineKeypad, Keypad] |
اختیاری - کیبورد معمولی یا اینلاین همراه پیام. |
خروجی:
ApiResponse
یک شیء از نوع ApiResponse را برمیگرداند.
send_contact
اطلاعات یک مخاطب را برای چت موردنظر ارسال میکند.
| پارامتر | نوع | توضیحات |
|---|---|---|
| chat_id | Union[str, int] |
اجباری - شناسه چتی که مخاطب به آن ارسال میشود. |
| phone_number | str |
اجباری - شماره تلفن مخاطب. |
| first_name | str |
اجباری - نام مخاطب. |
| last_name | str |
اختیاری - نام خانوادگی مخاطب. |
| reply_to_message_id | int |
اختیاری - شناسه پیامی که اطلاعات مخاطب در پاسخ به آن ارسال میشود. |
| markup | Union[InlineKeypad, Keypad] |
اختیاری - کیبورد معمولی یا اینلاین همراه پیام. |
خروجی:
ApiResponse
یک شیء از نوع ApiResponse را برمیگرداند.
send_action
وضعیت فعالیت ربات را در چت نمایش میدهد؛ مانند در حال تایپ بودن یا در حال بارگذاری فایل.
| پارامتر | نوع | توضیحات |
|---|---|---|
| chat_id | Union[str, int] |
اجباری - شناسه چتی که وضعیت فعالیت در آن نمایش داده میشود. |
| action | Union[str, ActionsEnum] |
اجباری - نوع فعالیتی که باید نمایش داده شود. این مقدار میتواند بهصورت رشته یا یکی از مقادیر ActionsEnum باشد. |
خروجی:
ApiResponse
یک شیء از نوع ApiResponse را برمیگرداند.
get_file
اطلاعات مربوط به یک فایل را با استفاده از شناسه آن دریافت میکند.
| پارامتر | نوع | توضیحات |
|---|---|---|
| file_id | str |
اجباری - شناسه فایل موردنظر. |
خروجی:
File
شیئی شامل اطلاعات فایل مانند شناسه، مسیر و سایر مشخصات آن.
answer_callback_query
به یک Callback Query پاسخ میدهد. از این متد برای حذف حالت انتظار دکمههای اینلاین و نمایش پیام یا هشدار به کاربر استفاده میشود.
| پارامتر | نوع | توضیحات |
|---|---|---|
| callback_id | str |
اجباری - شناسه Callback Query. |
| text | str |
اختیاری - متنی که برای کاربر نمایش داده میشود. |
| show_alert | bool |
اختیاری - اگر True باشد، متن بهصورت پنجره هشدار نمایش داده میشود؛ در غیر این صورت بهصورت اعلان کوتاه نمایش داده خواهد شد. مقدار پیشفرض False است. |
خروجی:
ApiResponse
یک شیء از نوع ApiResponse را برمیگرداند.
ask_review
از کاربر درخواست میکند که برای ربات یا برنامه بازخورد (Review) ثبت کند.
| پارامتر | نوع | توضیحات |
|---|---|---|
| user_id | int |
اجباری - شناسه کاربری که درخواست بازخورد برای او ارسال میشود. |
| delay | int |
اجباری - مدت زمان تأخیر قبل از نمایش درخواست بازخورد، بر حسب ثانیه. مقدار این پارامتر باید بین 0 تا 10 باشد. |
خروجی:
ApiResponse
یک شیء از نوع ApiResponse را برمیگرداند.
ban_member
یک کاربر را از چت یا گروه مسدود میکند.
| پارامتر | نوع | توضیحات |
|---|---|---|
| chat_id | Union[str, int] |
اجباری - شناسه چتی که کاربر در آن مسدود میشود. |
| user_id | int |
اجباری - شناسه کاربری که باید مسدود شود. |
خروجی:
ApiResponse
یک شیء از نوع ApiResponse را برمیگرداند.
unban_member
محدودیت یک کاربر را در چت یا گروه حذف میکند.
| پارامتر | نوع | توضیحات |
|---|---|---|
| chat_id | Union[str, int] |
اجباری - شناسه چتی که کاربر در آن از حالت مسدود خارج میشود. |
| user_id | int |
اجباری - شناسه کاربری که باید از حالت مسدود خارج شود. |
| only_if_banned | bool |
اختیاری - اگر True باشد، عملیات تنها در صورتی انجام میشود که کاربر قبلاً مسدود شده باشد. مقدار پیشفرض False است. |
خروجی:
ApiResponse
یک شیء از نوع ApiResponse را برمیگرداند.
promote_member
سطح دسترسی یک کاربر را در چت یا گروه ارتقا داده و مجوزهای مدیریتی موردنظر را به او اعطا میکند.
| پارامتر | نوع | توضیحات |
|---|---|---|
| chat_id | Union[str, int] |
اجباری - شناسه چتی که کاربر در آن ارتقا پیدا میکند. |
| user_id | int |
اجباری - شناسه کاربری که باید ارتقا داده شود. |
| can_change_info | bool |
اختیاری - اجازه تغییر اطلاعات چت یا گروه. |
| can_post_messages | bool |
اختیاری - اجازه ارسال پیام در کانال. |
| can_edit_messages | bool |
اختیاری - اجازه ویرایش پیامها. |
| can_delete_messages | bool |
اختیاری - اجازه حذف پیامها. |
| can_manage_video_chats | bool |
اختیاری - اجازه مدیریت چتهای تصویری. |
| can_invite_users | bool |
اختیاری - اجازه دعوت کاربران جدید. |
| can_restrict_members | bool |
اختیاری - اجازه محدود کردن کاربران. |
خروجی:
ApiResponse
یک شیء از نوع ApiResponse را برمیگرداند.
set_chat_photo
تصویر پروفایل چت یا گروه را تغییر میدهد. تصویر میتواند از طریق شناسه فایل، آدرس اینترنتی یا فایل محلی ارسال شود.
| پارامتر | نوع | توضیحات |
|---|---|---|
| chat_id | Union[str, int] |
اجباری - شناسه چتی که تصویر آن تغییر میکند. |
| file | str |
اجباری - شناسه فایل، آدرس اینترنتی یا مسیر فایل محلی. |
| is_local_file | bool |
اختیاری - اگر True باشد، مقدار file بهعنوان مسیر فایل محلی در نظر گرفته میشود. مقدار پیشفرض False است. |
خروجی:
ApiResponse
یک شیء از نوع ApiResponse را برمیگرداند.
leave_chat
ربات را از چت، گروه یا کانال موردنظر خارج میکند.
| پارامتر | نوع | توضیحات |
|---|---|---|
| chat_id | Union[str, int] |
اجباری - شناسه چتی که ربات باید آن را ترک کند. |
خروجی:
ApiResponse
یک شیء از نوع ApiResponse را برمیگرداند.
get_chat
اطلاعات کامل یک چت، گروه یا کانال را دریافت میکند.
| پارامتر | نوع | توضیحات |
|---|---|---|
| chat_id | Union[str, int] |
اجباری - شناسه چت، گروه یا کانال موردنظر. |
خروجی:
ChatFullInfo
شیئی شامل اطلاعات کامل چت، گروه یا کانال.
get_chat_administrators
لیست مدیران یک چت، گروه یا کانال را دریافت میکند.
| پارامتر | نوع | توضیحات |
|---|---|---|
| chat_id | Union[str, int] |
اجباری - شناسه چت، گروه یا کانال موردنظر. |
خروجی:
ChatAdministratorsResponse
شیئی شامل اطلاعات مدیران چت، گروه یا کانال.
get_chat_member_count
تعداد اعضای یک چت، گروه یا کانال را دریافت میکند.
| پارامتر | نوع | توضیحات |
|---|---|---|
| chat_id | Union[str, int] |
اجباری - شناسه چت، گروه یا کانال موردنظر. |
خروجی:
Union[int, None]
در صورت موفقیت، تعداد اعضای چت را بهصورت عدد صحیح برمیگرداند؛ در غیر این صورت مقدار None برگردانده میشود.
get_chat_member
اطلاعات یک عضو از چت، گروه یا کانال را دریافت میکند.
| پارامتر | نوع | توضیحات |
|---|---|---|
| chat_id | Union[str, int] |
اجباری - شناسه چت، گروه یا کانال. |
| user_id | int |
اجباری - شناسه کاربری عضوی که اطلاعات آن دریافت میشود. |
خروجی:
ChatMember
شیئی شامل اطلاعات عضو موردنظر و وضعیت او در چت.
pin_message
یک پیام را در چت، گروه یا کانال سنجاق میکند.
| پارامتر | نوع | توضیحات |
|---|---|---|
| chat_id | Union[str, int] |
اجباری - شناسه چتی که پیام در آن سنجاق میشود. |
| message_id | int |
اجباری - شناسه پیامی که باید سنجاق شود. |
خروجی:
ApiResponse
یک شیء از نوع ApiResponse را برمیگرداند.
unpin_message
پیام سنجاقشده را از حالت سنجاق خارج میکند.
| پارامتر | نوع | توضیحات |
|---|---|---|
| chat_id | Union[str, int] |
اجباری - شناسه چتی که پیام در آن قرار دارد. |
| message_id | int |
اجباری - شناسه پیامی که باید از حالت سنجاق خارج شود. |
خروجی:
ApiResponse
یک شیء از نوع ApiResponse را برمیگرداند.
unpin_all_message
تمام پیامهای سنجاقشده را از چت، گروه یا کانال حذف میکند.
| پارامتر | نوع | توضیحات |
|---|---|---|
| chat_id | Union[str, int] |
اجباری - شناسه چتی که پیامهای سنجاقشده آن حذف میشوند. |
خروجی:
ApiResponse
یک شیء از نوع ApiResponse را برمیگرداند.
set_chat_description
توضیحات چت، گروه یا کانال را تغییر میدهد.
| پارامتر | نوع | توضیحات |
|---|---|---|
| chat_id | Union[str, int] |
اجباری - شناسه چتی که توضیحات آن تغییر میکند. |
| description | str |
اجباری - متن توضیحات جدید چت. |
خروجی:
ApiResponse
یک شیء از نوع ApiResponse را برمیگرداند.
delete_chat_photo
تصویر پروفایل چت، گروه یا کانال را حذف میکند.
| پارامتر | نوع | توضیحات |
|---|---|---|
| chat_id | Union[str, int] |
اجباری - شناسه چتی که تصویر آن حذف میشود. |
خروجی:
ApiResponse
یک شیء از نوع ApiResponse را برمیگرداند.
create_invite_link
یک لینک دعوت جدید برای چت، گروه یا کانال ایجاد میکند.
| پارامتر | نوع | توضیحات |
|---|---|---|
| chat_id | Union[str, int] |
اجباری - شناسه چتی که لینک دعوت برای آن ایجاد میشود. |
خروجی:
Union[str, None]
در صورت موفقیت، لینک دعوت ایجادشده را بهصورت رشته برمیگرداند؛ در غیر این صورت مقدار None برگردانده میشود.
revoke_invite_link
یک لینک دعوت را باطل میکند تا دیگر قابل استفاده نباشد.
| پارامتر | نوع | توضیحات |
|---|---|---|
| chat_id | Union[str, int] |
اجباری - شناسه چتی که لینک دعوت متعلق به آن است. |
| invite_link | str |
اجباری - لینک دعوتی که باید باطل شود. |
خروجی:
Union[str, None]
در صورت موفقیت، لینک دعوت جدید یا بهروزرسانیشده را برمیگرداند؛ در غیر این صورت مقدار None برگردانده میشود.
export_invite_link
لینک دعوت اصلی چت را دریافت میکند.
| پارامتر | نوع | توضیحات |
|---|---|---|
| chat_id | Union[str, int] |
اجباری - شناسه چتی که لینک دعوت آن دریافت میشود. |
خروجی:
Union[str, None]
در صورت موفقیت، لینک دعوت را بهصورت رشته برمیگرداند؛ در غیر این صورت مقدار None برگردانده میشود.
edit_message
متن یک پیام ارسالشده را ویرایش میکند.
| پارامتر | نوع | توضیحات |
|---|---|---|
| chat_id | Union[str, int] |
اجباری - شناسه چتی که پیام در آن قرار دارد. |
| message_id | int |
اجباری - شناسه پیامی که باید ویرایش شود. |
| text | str |
اجباری - متن جدید پیام. |
| markup | Union[InlineKeypad, Keypad] |
اختیاری - کیبورد جدیدی که باید همراه پیام ثبت شود. |
خروجی:
EditedMessage
شیئی شامل اطلاعات پیام ویرایششده.
edit_caption
متن توضیح (Caption) یک پیام رسانهای را ویرایش میکند.
| پارامتر | نوع | توضیحات |
|---|---|---|
| chat_id | Union[str, int] |
اجباری - شناسه چتی که پیام در آن قرار دارد. |
| message_id | int |
اجباری - شناسه پیام رسانهای که باید ویرایش شود. |
| caption | str |
اختیاری - متن توضیح جدید. |
| markup | Union[InlineKeypad, Keypad] |
اختیاری - کیبورد جدیدی که باید همراه پیام ثبت شود. |
خروجی:
EditedMessage
شیئی شامل اطلاعات پیام ویرایششده.
edit_markup
کیبورد (Reply Markup) یک پیام را ویرایش میکند.
| پارامتر | نوع | توضیحات |
|---|---|---|
| chat_id | Union[str, int] |
اجباری - شناسه چتی که پیام در آن قرار دارد. |
| message_id | int |
اجباری - شناسه پیامی که باید کیبورد آن ویرایش شود. |
| markup | Union[InlineKeypad, Keypad] |
اجباری - کیبورد جدیدی که باید برای پیام تنظیم شود. |
خروجی:
EditedMessage
شیئی شامل اطلاعات پیام ویرایششده.
delete_message
یک پیام را از چت، گروه یا کانال حذف میکند.
| پارامتر | نوع | توضیحات |
|---|---|---|
| chat_id | Union[str, int] |
اجباری - شناسه چتی که پیام در آن قرار دارد. |
| message_id | int |
اجباری - شناسه پیامی که باید حذف شود. |
خروجی:
ApiResponse
یک شیء از نوع ApiResponse را برمیگرداند.
send_invoice
یک فاکتور پرداخت برای کاربر ارسال میکند.
| پارامتر | نوع | توضیحات |
|---|---|---|
| chat_id | Union[str, int] |
اجباری - شناسه چتی که فاکتور برای آن ارسال میشود. |
| title | str |
اجباری - عنوان فاکتور. |
| description | str |
اجباری - توضیحات فاکتور. |
| payload | str |
اجباری - داده اختصاصی برای شناسایی تراکنش. |
| provider_token | str |
اجباری - توکن درگاه پرداخت. |
| prices | List[LabeledPrice] |
اجباری - لیست قیمتهای فاکتور. این لیست نباید خالی باشد. |
| photo_url | str |
اختیاری - آدرس تصویر فاکتور. |
| reply_to_message_id | int |
اختیاری - شناسه پیامی که فاکتور در پاسخ به آن ارسال میشود. |
خروجی:
MessageResponse
شیئی شامل اطلاعات پیام فاکتور ارسالشده.
create_invoice_link
یک لینک پرداخت برای فاکتور ایجاد میکند.
| پارامتر | نوع | توضیحات |
|---|---|---|
| title | str |
اجباری - عنوان فاکتور. |
| description | str |
اجباری - توضیحات فاکتور. |
| payload | str |
اجباری - داده اختصاصی برای شناسایی تراکنش. |
| provider_token | str |
اجباری - توکن درگاه پرداخت. |
| prices | List[LabeledPrice] |
اجباری - لیست قیمتهای فاکتور. این لیست نباید خالی باشد. |
خروجی:
Union[str, None]
در صورت موفقیت، لینک پرداخت را برمیگرداند؛ در غیر این صورت مقدار None برگردانده میشود.
answer_pre_checkout_query
به درخواست تأیید پرداخت (Pre Checkout Query) پاسخ میدهد.
| پارامتر | نوع | توضیحات |
|---|---|---|
| pre_checkout_query_id | str |
اجباری - شناسه درخواست پرداخت. |
| ok | bool |
اجباری - نتیجه بررسی درخواست پرداخت. |
| error_message | str |
اختیاری - پیام خطایی که در صورت رد شدن پرداخت برای کاربر نمایش داده میشود. |
خروجی:
ApiResponse
یک شیء از نوع ApiResponse را برمیگرداند.
inquire_transaction
اطلاعات یک تراکنش را با استفاده از شناسه آن دریافت میکند.
| پارامتر | نوع | توضیحات |
|---|---|---|
| transaction_id | str |
اجباری - شناسه تراکنش موردنظر. |
خروجی:
dict
دیکشنری شامل اطلاعات و وضعیت تراکنش.
create_referral_link
یک لینک دعوت (Referral) برای ربات ایجاد میکند که شامل Payload اختصاصی است.
| پارامتر | نوع | توضیحات |
|---|---|---|
| payload | Union[str, int] |
اجباری - دادهای که به لینک دعوت اضافه میشود و پس از شروع ربات قابل دریافت است. |
خروجی:
str
لینک Referral ایجادشده.
extract_referral_payload
Payload موجود در دستور /start را استخراج میکند.
| پارامتر | نوع | توضیحات |
|---|---|---|
| text | str |
اجباری - متن دریافتی از کاربر. |
خروجی:
Union[int, None]
در صورت معتبر بودن Payload، مقدار آن را بهصورت عدد صحیح برمیگرداند؛ در غیر این صورت مقدار None برگردانده میشود.
نکته: سیستم Referral این کتابخانه تنها از Payloadهای عددی پشتیبانی میکند. بنابراین متدهای مرتبط با Referral (مانند extract_referral_payload) و فیلترهای مربوطه فقط با مقادیر عددی مانند 826272 کار میکنند و Payloadهای متنی یا ترکیبی مانند abc7262 یا user_123 پشتیبانی نمیشوند.
create_new_sticker_set
یک مجموعه استیکر جدید ایجاد میکند.
| پارامتر | نوع | توضیحات |
|---|---|---|
| user_id | int |
اجباری - شناسه مالک مجموعه استیکر. |
| name | str |
اجباری - نام یکتای مجموعه استیکر. |
| title | str |
اجباری - عنوان مجموعه استیکر. |
| sticker | Any |
اجباری - لیست استیکرهایی که در مجموعه قرار میگیرند. |
خروجی:
dict
دیکشنری شامل نتیجه عملیات ایجاد مجموعه استیکر.
add_sticker_to_set
یک یا چند استیکر را به مجموعه استیکر موجود اضافه میکند.
| پارامتر | نوع | توضیحات |
|---|---|---|
| user_id | int |
اجباری - شناسه مالک مجموعه استیکر. |
| name | str |
اجباری - نام مجموعه استیکر. |
| sticker | Any |
اجباری - لیست استیکرهایی که باید به مجموعه اضافه شوند. |
خروجی:
dict
دیکشنری شامل نتیجه عملیات افزودن استیکر.
upload_sticker_file
فایل استیکر را برای استفاده در مجموعه استیکر بارگذاری میکند.
| پارامتر | نوع | توضیحات |
|---|---|---|
| user_id | int |
اجباری - شناسه کاربری مالک استیکر. |
| sticker | Any |
اجباری - فایل یا شناسه استیکر برای بارگذاری. |
خروجی:
dict
دیکشنری شامل اطلاعات فایل بارگذاریشده.
create_download_link
لینک دانلود یک فایل را با استفاده از مسیر آن ایجاد میکند.
| پارامتر | نوع | توضیحات |
|---|---|---|
| file_path | str |
اجباری - مسیر فایل دریافتشده از API. |
خروجی:
str
لینک کامل دانلود فایل.
download
یک فایل را از آدرس مشخص دانلود کرده و در سیستم ذخیره میکند.
| پارامتر | نوع | توضیحات |
|---|---|---|
| url | str |
اجباری - آدرس فایل برای دانلود. |
| file_name | str |
اختیاری - نام فایل ذخیرهشده. در صورت مشخص نشدن، نام فایل از انتهای URL استخراج میشود. |
خروجی:
bool
در صورت دانلود موفق مقدار True برگردانده میشود.
run
ربات را اجرا میکند. بسته به تنظیمات، ربات در حالت Polling یا Webhook شروع به دریافت و پردازش بهروزرسانیها خواهد کرد.
| پارامتر | نوع | توضیحات |
|---|---|---|
| timeout | int |
اختیاری - مدت زمان انتظار برای دریافت بهروزرسانیها در حالت Polling. مقدار پیشفرض 15 ثانیه است. |
| sleep | float |
اختیاری - مدت زمان توقف بین درخواستهای Polling زمانی که بهروزرسانی جدیدی وجود ندارد. مقدار پیشفرض 0.7 ثانیه است. |
| webhook_path | str |
اختیاری - مسیر Endpoint مربوط به Webhook. مقدار پیشفرض /webhook است. |
| host | str |
اختیاری - آدرس میزبان سرور Webhook. مقدار پیشفرض 0.0.0.0 است. |
| port | int |
اختیاری - پورتی که سرور Webhook روی آن اجرا میشود. مقدار پیشفرض 8000 است. |
نحوه استفاده از وبهوک
# pip install gyron[webhook]
from gyron.bot import BotClient
import asyncio
token = 'TOKEN'
webhook_url = 'https://dgjzs-217-218-35-75.free.pinggy.net/webhk'
app = BotClient(token, use_webhook=True)
@app.on_update()
async def start(update):
await app.reply('سلام')
async def main():
res = await app.set_webhook(webhook_url)
if res.ok:
print('started')
await app.run(webhook_path='/webhk')
asyncio.run(main())