filters
فیلترها برای محدود کردن اجرای هندلرها استفاده میشوند. هر فیلتر یک شرط را روی Update دریافتی بررسی میکند و تنها در صورتی که شرط برقرار باشد، هندلر اجرا میشود.
در صورتی که چند فیلتر بهصورت همزمان برای یک هندلر تعریف شوند، تمام فیلترها باید برقرار باشند تا هندلر اجرا شود.
text()
بررسی میکند که پیام دارای متن باشد یا متن آن با الگوی مشخصشده مطابقت داشته باشد.
| پارامتر | نوع | توضیحات |
|---|---|---|
| pattern | str \| Pattern \| None |
اختیاری - الگوی موردنظر برای جستجو در متن پیام. در صورت مشخص نشدن، فقط وجود داشتن متن بررسی میشود. |
caption()
بررسی میکند که پیام دارای Caption باشد یا Caption آن با الگوی مشخصشده مطابقت داشته باشد.
| پارامتر | نوع | توضیحات |
|---|---|---|
| pattern | str \| Pattern \| None |
اختیاری - الگوی موردنظر برای جستجو در Caption. در صورت مشخص نشدن، فقط وجود داشتن Caption بررسی میشود. |
private()
بررسی میکند که پیام در گفتوگوی خصوصی (Private Chat) ارسال شده باشد.
| پارامتر | نوع | توضیحات |
|---|---|---|
| - | - | این فیلتر پارامتری ندارد. |
group()
بررسی میکند که پیام در گروه ارسال شده باشد.
| پارامتر | نوع | توضیحات |
|---|---|---|
| - | - | این فیلتر پارامتری ندارد. |
channel()
بررسی میکند که پیام در کانال ارسال شده باشد.
| پارامتر | نوع | توضیحات |
|---|---|---|
| - | - | این فیلتر پارامتری ندارد. |
new_member()
بررسی میکند که آیا در Update دریافتی، کاربر جدیدی به چت اضافه شده است یا خیر.
| پارامتر | نوع | توضیحات |
|---|---|---|
| - | - | این فیلتر پارامتری ندارد. |
left_member()
بررسی میکند که آیا کاربری از چت خارج شده یا از آن حذف شده است.
| پارامتر | نوع | توضیحات |
|---|---|---|
| - | - | این فیلتر پارامتری ندارد. |
is_referral()
بررسی میکند که پیام دریافتی شامل دستور /start همراه با یک Payload عددی باشد.
| پارامتر | نوع | توضیحات |
|---|---|---|
| - | - | این فیلتر پارامتری ندارد. |
نکته: سیستم Referral این کتابخانه تنها از Payloadهای عددی پشتیبانی میکند. بنابراین این فیلتر فقط دستورهایی مانند
/start 826272را معتبر میداند و Payloadهای متنی یا ترکیبی مانند/start abc7262را تشخیص نمیدهد.
is_joined()
بررسی میکند که کاربر در تمام چتها یا کانالهای مشخصشده عضو باشد.
| پارامتر | نوع | توضیحات |
|---|---|---|
*chat_ids |
Union[str, int] |
اجباری - یک یا چند شناسه چت یا کانال که عضویت کاربر در آنها بررسی میشود. تنها در صورتی شرط برقرار است که کاربر در همه چتها یا کانالهای مشخصشده عضو باشد. |
not_is_joined()
بررسی میکند که کاربر در هیچیک از چتها یا کانالهای مشخصشده عضو نباشد.
| پارامتر | نوع | توضیحات |
|---|---|---|
*chat_ids |
Union[str, int] |
اجباری - یک یا چند شناسه چت یا کانال که عضویت کاربر در آنها بررسی میشود. تنها در صورتی شرط برقرار است که کاربر در هیچکدام از چتها یا کانالهای مشخصشده عضو نباشد. |
pre_checkout_query()
بررسی میکند که Update دریافتی مربوط به درخواست تأیید پرداخت (Pre Checkout Query) باشد.
| پارامتر | نوع | توضیحات |
|---|---|---|
| - | - | این فیلتر پارامتری ندارد. |
at_state()
بررسی میکند که کاربر در یک State مشخص قرار داشته باشد یا بهطور کلی دارای State فعال باشد.
| پارامتر | نوع | توضیحات |
|---|---|---|
| manager | StateManager |
اجباری - مدیر مدیریت Stateها که وضعیت کاربر از طریق آن بررسی میشود. |
| state | str \| None |
اختیاری - نام State موردنظر. در صورت مشخص نشدن، فقط وجود داشتن یک State فعال بررسی میشود. |
callback_query()
بررسی میکند که Update دریافتی یک Callback Query باشد یا مقدار data آن با مقدار مشخصشده برابر باشد.
| پارامتر | نوع | توضیحات |
|---|---|---|
| button_data | str \| None |
اختیاری - داده مورد انتظار دکمه. در صورت مشخص نشدن، فقط وجود داشتن Callback Query بررسی میشود. |
contact()
بررسی میکند که پیام شامل Contact باشد یا شماره تماس آن با مقدار مشخصشده برابر باشد.
| پارامتر | نوع | توضیحات |
|---|---|---|
| phone_number | str \| None |
اختیاری - شماره تماس مورد انتظار. در صورت مشخص نشدن، فقط وجود داشتن Contact بررسی میشود. |
location()
بررسی میکند که پیام شامل موقعیت مکانی (Location) باشد.
| پارامتر | نوع | توضیحات |
|---|---|---|
| - | - | این فیلتر پارامتری ندارد. |
forward()
بررسی میکند که پیام فوروارد شده باشد.
| پارامتر | نوع | توضیحات |
|---|---|---|
| - | - | این فیلتر پارامتری ندارد. |
document()
بررسی میکند که پیام شامل فایل (Document) باشد.
| پارامتر | نوع | توضیحات |
|---|---|---|
| - | - | این فیلتر پارامتری ندارد. |
photo()
بررسی میکند که پیام شامل تصویر باشد.
| پارامتر | نوع | توضیحات |
|---|---|---|
| - | - | این فیلتر پارامتری ندارد. |
reply()
بررسی میکند که پیام، پاسخ (Reply) به پیام دیگری باشد.
| پارامتر | نوع | توضیحات |
|---|---|---|
| - | - | این فیلتر پارامتری ندارد. |
voice()
بررسی میکند که پیام شامل پیام صوتی (Voice) باشد.
| پارامتر | نوع | توضیحات |
|---|---|---|
| - | - | این فیلتر پارامتری ندارد. |
animation()
بررسی میکند که پیام شامل Animation باشد.
| پارامتر | نوع | توضیحات |
|---|---|---|
| - | - | این فیلتر پارامتری ندارد. |
video()
بررسی میکند که پیام شامل ویدئو باشد.
| پارامتر | نوع | توضیحات |
|---|---|---|
| - | - | این فیلتر پارامتری ندارد. |
sticker()
بررسی میکند که پیام شامل استیکر باشد.
| پارامتر | نوع | توضیحات |
|---|---|---|
| - | - | این فیلتر پارامتری ندارد. |
successful_payment()
بررسی میکند که Update مربوط به پرداخت موفق باشد.
| پارامتر | نوع | توضیحات |
|---|---|---|
| - | - | این فیلتر پارامتری ندارد. |
invoice()
بررسی میکند که پیام شامل Invoice باشد.
| پارامتر | نوع | توضیحات |
|---|---|---|
| - | - | این فیلتر پارامتری ندارد. |
entity()
بررسی میکند که پیام دارای Entity باشد.
| پارامتر | نوع | توضیحات |
|---|---|---|
| - | - | این فیلتر پارامتری ندارد. |
equals()
بررسی میکند که متن پیام دقیقاً با مقدار مشخصشده برابر باشد.
| پارامتر | نوع | توضیحات |
|---|---|---|
| text | str |
اجباری - متن مورد انتظار. |
is_admin()
بررسی میکند که ارسالکننده پیام، مدیر (Administrator) چت باشد.
| پارامتر | نوع | توضیحات |
|---|---|---|
| - | - | این فیلتر پارامتری ندارد. |
is_member()
بررسی میکند که ارسالکننده پیام، عضو عادی (Member) چت باشد.
| پارامتر | نوع | توضیحات |
|---|---|---|
| - | - | این فیلتر پارامتری ندارد. |
is_creator()
بررسی میکند که ارسالکننده پیام، سازنده (Creator) چت باشد.
| پارامتر | نوع | توضیحات |
|---|---|---|
| - | - | این فیلتر پارامتری ندارد. |
is_restricted()
بررسی میکند که ارسالکننده پیام دارای وضعیت Restricted باشد.
| پارامتر | نوع | توضیحات |
|---|---|---|
| - | - | این فیلتر پارامتری ندارد. |
user_id()
بررسی میکند که شناسه فرستنده با مقدار مشخصشده برابر باشد.
| پارامتر | نوع | توضیحات |
|---|---|---|
| id | str \| int |
اجباری - شناسه کاربر مورد انتظار. |
chat_id()
بررسی میکند که شناسه چت با مقدار مشخصشده برابر باشد.
| پارامتر | نوع | توضیحات |
|---|---|---|
| id | str \| int |
اجباری - شناسه چت مورد انتظار. |
command()
بررسی میکند که پیام یک دستور (Command) باشد یا با دستور مشخصشده مطابقت داشته باشد.
| پارامتر | نوع | توضیحات |
|---|---|---|
| command | str \| None |
اختیاری - نام دستور بدون /. در صورت مشخص نشدن، فقط بررسی میشود که پیام با / شروع شده باشد. |