کتابخانۀ کار با API ایتا برای پایتون

ایتاپای‌کیت یک ابزار غیررسمی به زبان پایتون است که راهکار هایی برای استفاده از API های این پیامرسان را ارائه می‌دهد.

نکته: برای آنکه بتوانید در کانال‌ها و گروه‌ها پیغام یا فایل ارسال کنید، قبل از هرکاری لازم است، کاربر @sender را در کانال یا گروه خود به عنوان مدیر اضافه کنید. نکته: با توجه به آپدیت مداوم نسخه وب ایتا توسط شرکت سازنده ممکن است برخی از ویژگی های این کتابخانه موقتا از کار بیوفتد، اگر با چنین چیزی مواجه شدید، می‌توانید با ایجاد issue در مخزن گیت‌هاب، ما را مطلع کنید تا هرچه سریع‌تر مشکل را برطرف سازیم.

نصب

شما می‌توانید با دستور زیر آخرین نسخۀ eitaapykit را برای پایتون دریافت نمایید:

pip install eitaa

همچنین نسخه درحال توسعه نیز از طریق دستور زیر قابل نصب است:

pip install git+https://github.com/bistcuite/eitaapykit.git

کلاس پایۀ Eitaa

برای اینکه بتوانید پیغام یا فایل ارسال کنید، لازم است ابتدا به صورت زیر یک نمونه(instance) از آن ایجاد کنید و سپس توکنی را که از سایت ایتایار دریافت کرده‌اید را به عنوان پارامتر به کلاس Eitaa بدهید:

from eitaa import Eitaa
token = "your eitaayar.ir token"
e = Eitaa(token)

ارسال پیغام

برای ارسال پیغام(پیام به صورت متن) کافی است از متد send_message در کلاس Eitaa استفاده کنید.

پارامتر های متد send_message:

• chat_id : شناسۀ یکتای کانال یا گروه.

- برای ارسال پیغام به کانال، کافی است آیدی کانال خود را بدون @ به آن نسبت بدهید.

- اگر کانال شما خصوصی است و یا قصد ارسال پیغام به یک گروه را دارید، کافی است لینک آن را نسبت بدهید.

• text : str : متن پیغامی که قصد ارسال آن را دارید.

• pin : bool(اختیاری) : با تغییر آن به True پیغام ارسالی در چت پین می‌شود، به صورت پیشفرض False است.

• view_to_delete : int(اختیاری) : اگر تعداد بازدید های پیغام به این عدد برسد، به صورت خودکار حذف خواهد شد.

• disable_notification : bool(اختیاری): با تنظیم آن بر روی True هیچگونه اعلانی برای مخاطبان ارسال نمی‌شود، به صورت پیشفرض روی False تنظیم شده است.

• reply_to_message_id : int(اختیاری): شناسۀ پیامی که می‌خواهید پیغام بر روی آن پاسخ داده شود.

• date(اختیاری) : فرمت زمانی Unix که می‌تواند زمانی در آینده را برای ارسال پیام مشخص کند.

مثال:

print(e.send_message("chat id","message text",pin=True))

تابع یک پاسخ JSON حاوی اطلاعاتی در مورد پیام ارسال شده برمی گرداند که حاوی فیلد های زیر است:

• ok (بولین):

- True: به معنی این است پیغام با موفقیت ارسال شده است.

- False: به معنی عدم موفقیت در ارسال پیام است.

• description (رشته‌ای، اختیاری): (تنها در صورتی ظاهر می‌شود که فیلد ok برابر با False باشد) این فیلد توضیحی دربارۀ علت ارسال نشدن پیام ارائه می‌دهد.

ارسال فایل

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

پارامتر های متد send_file:

• chat_id : شناسۀ یکتای کانال یا گروه.

- برای ارسال پیغام به کانال، کافی است آیدی کانال خود را بدون @ به آن نسبت بدهید.

- اگر کانال شما خصوصی است و یا قصد ارسال پیغام به یک گروه را دارید، کافی است لینک آن را نسبت بدهید. - file: str: مسیر فایلی که می‌خواهید ارسال کنید. - text : str : متن پیغامی که قصد ارسال آن را دارید.

• pin : bool(اختیاری) : با تغییر آن به True پیغام ارسالی در چت پین می‌شود، به صورت پیشفرض False است.

• view_to_delete : int(اختیاری) : اگر تعداد بازدید های پیغام به این عدد برسد، به صورت خودکار حذف خواهد شد.

• disable_notification : bool(اختیاری): با تنظیم آن بر روی True هیچگونه اعلانی برای مخاطبان ارسال نمی‌شود، به صورت پیشفرض روی False تنظیم شده است.

• reply_to_message_id : int(اختیاری): شناسۀ پیامی که می‌خواهید پیغام بر روی آن پاسخ داده شود.

• date(اختیاری) : فرمت زمانی Unix که می‌تواند زمانی در آینده را برای ارسال پیام مشخص کند.

مثال:

print(e.send_file("chat id","caption","README.txt",pin=True))

تابع یک پاسخ JSON حاوی اطلاعاتی در مورد پیام ارسال شده برمی گرداند که حاوی فیلد های زیر است:

• ok (بولین):

- True: به معنی این است پیغام با موفقیت ارسال شده است.

- False: به معنی عدم موفقیت در ارسال پیام است.

• description (رشته‌ای، اختیاری): (تنها در صورتی ظاهر می‌شود که فیلد ok برابر با False باشد) این فیلد توضیحی دربارۀ علت ارسال نشدن پیام ارائه می‌دهد.

دریافت اطلاعات یک کانال یا کاربر

شما می‌توانید با استفاده از متد get_info اطلاعات عمومی یک کانال و یا کاربر را بدست بیاورید.

پارامتر های متد get_info : - channel_or_user_id: str: شناسۀ عمومی کانال یا کاربر

مثال:

from eitaa import Eitaa
info = Eitaa.get_info("eitaa_faq")
print(info)

نمونه اطلاعات دریافتی:

{

    "name": "راهنمای جامع ایتا",

    "image_url": "will contains a url",

    "users": "205.9K",

    "description": "پاسخ به پرسش\u200cهای متداول کاربران ایتا\n\nپشتیبانی کاربران:\n@support\n\nکانال اطلاع\u200cرسانی رسمی:\n@eitaa\n\nوبسایت رسمی برنامه:\nhttps://eitaa.com", "is_verified": true,

    "is_channel": true

}

دریافت آخرین پیام های یک کانال عمومی

متد get_latest_messages که یک متد ایستا(static method) است، می‌تواند برای دریافت چند پیام آخر یک کانال(معمولا ده پیام) استفاده شود. مقدار خروجی این متد یک لیست متشکل از dictهایی خواهد بود که هر یک حاوی اطلاعات هر پیام است و فیلد هایی به شکل زیر دارد: - text : متن پیام

• image_link : آدرس اینترنتی تصویر پیام(اگر پیام به صورت کاملا متنی باشد، خالی خواهد بود)

• views : تعداد بازدید های پیام

• iso_time : زمان ارسال پیام به فرمت ISO

• message_number: شمارۀ پیام مثال:

from eitaa import Eitaa
messages = Eitaa.get_latest_messages('eitaa_faq')

دریافت یک پست خاص از یک کانال

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

Eitaa.get_message("YOUR_CHANNEL_ID",YOUR_POST_ID)

تابع get_message یک دیکشنری شامل اطلاعات زیر را برمی‌گرداند:

{
  "owner_name" : ... # نام کانال
  "channel_url" : ... # لینک کانال
  "message_url" : ... # لینک پست
  "message_text" : ... # متن پست
  "views" : ... # تعداد بازدید پست
  "date" : ... # تاریخ پست شدن
  "service_date" : ... # تاریخ سرویس
  "author_name" : ... # نام نویسنده
  "video_time" : ... # زمان ویدئو
  "video_thumb" : ... # لینک تامنیل ویدئو
}

دریافت هشتگ های ترندشده

متد get_trends که یک متد ایستا(static method) در کلاس پایۀ Eitaa است، می‌تواند برای استخراج هشتگ های ترندشده در ایتا، در بازه های زمانی متفاوت استفاده شود. این متد یک لیست متشکل از چهار dict یا دیکشنری برمی‌گرداند:

• last_12_hours: لیست هشتگ های ترند شده در 12 ساعت گذشته همراه با تعداد هشتگ‌ها(که خودش متشکل از لیست از دیکشنری‌ها است که دارای دو فیلد name و count هستند، که شامل نام هشتگ و تعداد آن می‌شود).

• last_24_hours: لیست هشتگ های ترند شده در 24 ساعت گذشته همراه با تعداد هشتگ‌ها(که خودش متشکل از لیست از دیکشنری‌ها است که دارای دو فیلد name و count هستند، که شامل نام هشتگ و تعداد آن می‌شود).

• last_7_days: لیست هشتگ های ترند شده در 7 روز گذشته همراه با تعداد هشتگ‌ها(که خودش متشکل از لیست از دیکشنری‌ها است که دارای دو فیلد name و count هستند، که شامل نام هشتگ و تعداد آن می‌شود).

• last_30_days: لیست هشتگ های ترند شده در 30 روز گذشته همراه با تعداد هشتگ‌ها(که خودش متشکل از لیست از دیکشنری‌ها است که دارای دو فیلد name و count هستند، که شامل نام هشتگ و تعداد آن می‌شود).

مثال:

from eitaa import Eitaa
trends = Eitaa.get_trends()

خروجی نمونه:

{

    "last_12_hours": [

        {"name": "#اربعین", "count": "+1500"},

        {"name": "#امام_حسین", "count": "+500"},

        {"name": "#امام_زمان", "count": "+500"},

        {"name": "#شب_جمعه", "count": "+400"},

        {"name": "#کربلا", "count": "+300"}

    ],

    "last_24_hours": [

        {"name": "#اربعین", "count": "+3000"},

        {"name": "#امام_حسین", "count": "+1000"},

        {"name": "#امام_زمان", "count": "+700"},

        {"name": "#کربلا", "count": "+600"},

        {"name": "#شب_جمعه", "count": "+400"}

    ],

    ...

}

ساخت بات(برنامه) ایتا

برنامه یک گفت‌وگو در ایتاست که امکان ارسال و دریافت پیام، پیوست برنامک و اجرای برنامک‌ها را فراهم می‌کند. در برخی از پیامرسان‌ها این وظیفه را «بات» انجام می‌دهد.

چگونه یک بات بسازیم؟

• با زدن روی این لینک، وارد سامانه ایتایار شوید و به پنل کاربری خود بروید (اگر اکانت ندارید، ابتدا لازم است ثبت‌نام کنید)
• سپس از انتهای منوی سمت راست، روی دکمه «برنامه» بزنید.
• پس از انتخاب گزینه «افزودن برنامه» در صفحه جدید، اطلاعات مربوط به برنامه، شامل تصویر پروفایل، نام، نام کاربری و بیوی برنامه را وارد کنید.
• همچنین عنوان دکمه، آدرس دکمه و عکس و پیام شروع برنامه را در همین بخش وارد کنید.
• حالا روی گزینه ساخت برنامه بزنید.

ارسال پیام به کاربران توسط بات

بعد از اینکه برنامه را ساختید حالا می‌توانید با استفاده از این کتابخانه توسط بات پیام متنی ارسال کنید، کافی است یک نمونه از کلاس Eitaa ایجاد کنید و از متد send_message_to_bot استفاده کنید:

from eitaa import Eitaa
token = "توکن دریافتی شما از ایتایار"
e = Eitaa(token)

chat_id = "شامل یک عدد چند رقمی است که از سایت ایتایار قابل دریافت است"
text = "متنی که می‌خواهید توسط بات ارسال شود"
e.send_message_to_bot(chat_id,text)

هشدار

ارسال پیام تنها زمانی ممکن است که کاربر به شما دسترسی ارسال داده باشد.

این دسترسی با زدن کلید شروع توسط کاربر و یا در زمان باز کردن با لینک مستقیم در یک پیغام از کاربر دریافت می‌شود.

درباره من

سلام من حسنم!

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