سیر تا پیاز ربات‌های تلگرام

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

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

 

ربات‌های تلگرام

مقدمه

همیشه تلگرام مارو با قابلیت های فوق‌العادش شگفت زده کرده. یکی از این قابلیت ها ربات های تلگرام هستن. یه API فوق‌العاده و کامل برای برقراری ارتباط با کاربرا و جواب دادن به اونها. جدیدا هم که قابلیت پاک کردن پیام اضافه شده و این پلتفرم دیگه هیچی کم نداره!

نمونه های خیلی زیادی هم داریم از ربات های تلگرام داریم که با ایده های طلایی تونستن کلی عضو بگیرن و پول دربیارن! پس این پلتفرم فوق‌العاده و این جامعه کاربری کم نظیر رو از دست ندید! اگر ایده شما به اندازه کافی خوب باشه به راحتی میتونید توی یک هفته بیشتر از ۱۰۰۰۰۰ عضو بگیرید. این تجربه شخصی خودمه :))

چرا یک مقاله دیگه؟

متاسفانه آموزش ها در زمینه ربات تلگرام در اکثر موارد کم کیفیت هستن، معمولا با مثال جواب شروع میشه و با یه مثال اینلاین در کمتر از دو صفحه کار تمومه. هیچ کجا شمارو با متد های تلگرام به درستی آشنا نمیکنن، یه نمای کلی از قضیه به شما نمیدن، و بدتر از اون مهرت های دیگه که برای ساختن یه ربات نیازه مثل مدیریت دیتابیس، لاگ گیری، مدیریت state کاربران و… رو ول میکنن به امان خدا!
من هم اینجا خیلی بیکارم و تصمیم گرفتم به مقاله طولانی که همه چی رو پوشش بده بتویسم، امیدوارم که بتونم کمکی کرده باشم.
در پایان هم به عنوان پروژه چندتا ربات ساده میسازیم.

مفاهیم پایه

بهتره اول سه تا مفهوم پایه رو توی ربات ها بررسی کنیم، آپدیت، آبجکت ها و متد ها.

آپدیت

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

آبجکت

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

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

درواقع هر آپدیت شامل آبجکت اون پیام/مکان/عکس/فیلم به همراه آبجکت فرستنده اون پیامه.

 

متد

متدهای API تلگرام قسمتیه که ربات شما با اونا میتونه کارهاشو انجام بده. برای مثل متد sendMessage برای فرستادن پیام استفاده میشه و از شما محل فرستادن پیام + متن پیام رو میخواد. همچنین میتونه مقادیر انتخابی دیگه ای مثل نشون دادن یا ندادن پیش‌نمایش لینک، نوع مارکاپ پیام و … رو قبول کنه.

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

http://api.telegram.org/bot[token]/[method]?[args]

سر وقتش دقیق براتون توضیحش میدم.

 

شروع کار با آپدیت ها

 

گرفتن آپدیت ها

دو روش برای این کار وجود داره، getUpdates و webhook.

متد getUpdates

راه ساده و بی دردسر گرفتن آپدیت ها که ماهم اینجا از اون استفاده میکنیم. چطور کار میکنه؟ وقتی این متد رو روی API صدا میزنیم آپدیت های جدید رو در قالب یه آرایه/لیست به ما میده. درواقع ما برای استفاده درست باید هر چند میلی ثانیه این متد رو صدا بزنیم و خبرای جدید رو بگیریم.

استفاده از webhook

در این شیوه به جای اینکه شما خبرارو از تلگرام بگیرید، اون خبرارو به شما میفرسته. برای این هم نیاز به یک وب‌سرور و گواهینامه SSL دارید. این روش میتونه سرعت بیشتری ارائه بده ولی درعوض زور سرور بیشتری میطلبه. حالا بهش کاری نداریم، ولی یه آموزش کوچیک برای راه اندازی گواهینامه SSL و متد های مخصوص getWebhookInfo، setWebhook و deleteWebhook پیوست میکنم.

 

بررسی یک آپدیت و شکل کلی اونا

بیاین یه نمونه آپدیت رو ببینیم و بررسیش کنیم.

یدونه ربات توی تلگرام میسازیم و توکن رو یه جای خوب نگه میداریم. (دقت کنید توکن کاملا باید خصوصی باشه و کسی بهش دسترسی نداشته باشه!!). یه پیام سلام هم بهش میدیم تا نمونه داشته باشیم.

و سپس متد getUpdates رو روی ربات اجرا میکنیم.

http://api.telegram.org/bot[token]/getUpdates

 

باید با همچین چیزی مواجه بشیم:

خوب بیاین بررسیش کنیم! (دقت کنید من آیدی خودم و آپدیت‌آیدی رو عوض کردم. ولی ۸ رقمی و ۹ رقمی بودنشو بدونید.)

فیلد ok که توی همه آپدیت ها هستش، نشون میده که متدی که از طریق API تلگرام اجرا کردید موفق کار کرده یا نه. در شرایطی مثل بلاک شدن ربات توسط کاربر این فیلد به false تغییر میکنه.

حالا میریم سراغ قسمت اصلی یا همون results. یه لیست شامل ۲ آپدیت که یکی مربوط به پیام استارت و دیگری مربوط به پیام سلام ما.

هر آپدیت یه ID مخصوص به خودش رو داره، که میشه باهاش کارهای مختلفی کرد. فعلا باهاش کاری نداریم.

میریم سراغ فیلد اصلی آپدیت یعنی message! بیاین ببینیم چیا توش میشه پیدا کرد!

یه ID مخصوص به پیام که هیچی، قسمت های بدرد بخور برای ما فیلد های from و chat و date و text هستن.

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

فیلد chat مربوط به چتیه که میام توی اون فرستاده شده، اینجا هم که نیاز به توضیح نداره! ID مخصوص، اسم چت و ویژگی های دیگه. اینجا چون چت خصوصیه یوزرنیم با یوزرنیم من یکیه، همینطور اسم چت.

فیلد text که متن پیام و date هم که تاریخ پیامه. نیاز به توضیح نداره 🙂

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

شروع کار با متد ها

متد ها راه واکنش نشون دادن ربات شما به آپدیت هاییه که براش میاد. بیاین یکیشو امتحان کنیم.

http://api.telegram.org/bot[token]/getMe

باید همچین جوابی بگیریم:

 

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

حالا یه متد دیگه رو امتحان میکنیم. فرستادن پیام!

http://api.telegram.org/bot[token]/sendMessage?chat_id=[user_id]&text=salam!

اگر توی این لینک توکن و آیدی خودتون رو بزارین باید یه پیام از باتتون بگیرید. به همین سادگی!

ولی بیاین بررسی کنیم که چطور همچین لینکی رو استفاده کنیم.

این قسمت از مستندات این متد رو توضیح داده. آرگیومنت هارو ببینید؛ ورودی های زیادی قبول میکنه. ولی فقط دوتاش نیازه. اگر به لینک بالاتر ساختیم دقت کنید، میبینید که ماهم دوتارو دادیم. آرگیومنت chat_id و text که مکان فرستادن و متن پیام رو مشخص میکنه.

اگر شکل URL بالا براتون عجیبه، بدونید که به قسمت بعد از علامت سوال میگن query string. این روش استاندارد برای فرستادن اطلاعات توی درخواست های HTTP محسوب میشه. شکل کلیش هم اینجوریه:

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

صفحه کلیدها در تلگرام

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

درخواست به API با صفحه کلید

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

توی مستندات گفته که ورودی صفحه کلید یا همون reply_markup توی فرستادن یا ویرایش پیام باید به صورت JSON باشه. ولی خوب چطور تلگرام تخیص میده که ما کدوم نوع کلید و صفحه کلید رو میخوایم؟ جوابش اولین ورودی مورد نیاز هر نوع صفحه کلیده. به آبجکت JSON زیر به عنوان ورودی reply_markup توی متد های مختلف دقت کنید:

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

توی درخواست بالا هر کلید هم به صورت یک آبجکت JSON دیگه اومده، که ویژگی های موردنیاز نوع InlineKeyboardButton یا همون کلید مخصوص صفحه های شیشه ای هستش.

دقت کنید که برای هر صفحه کلید یک نوع کلید مخصوص وجود داره.

نکته قابل توجه دیگه هم اینه که اگر سعی دارید از طریق مرورگر این آبجکت JSON رو برای API بفرستید، حتما به کاراکتر هایی مثل اسلش دقت کنید و اونارو اسکپ کنید، چون ممکنه جواب مورد نظرتون رو نگیرید.

 

فرستادن صفحه کلید با کتابخونه های متفرقه

ممکنه کتاب خونه مورد نظر شما برای ساختن صفحه کلید روش خودشو داشته باشه. در اکثر موارد کلاس های مخصوصی برای نوع صفحه کلید و کلیدا تعبیه شده که باید از اونا استفاده کنید. برای مثال شاید با همچین چیزی مواجه بشید که روش متداولیه:

صفحه کلید های شیشه ای

خوب با شکل کلی یک صفحه کلید و نوع فرستادن صفحه کلید شیشه ای آشنا شدیم، حالا ببینیم دقیقا این نوع رو چطور باید مدیریت کرد و ویژگی هاش چیه.

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

بازکردن آدرس سایت

بازکردن آدرس که چیز سختی نیست، مثال های بالای من یه ورودی url داشتن که باعث میشه وقتی روی کلید میزنید به آدرس اون هدایت بشید.

 

کار با callback ها

وقتی برای یک دکمه اینلاین ورودی callback_data رو تعیین میکنیم، موقع استفاده شدن از اون یک آپدیت برای ما میاد که یک فیلد مخصوص به اسم callback_query داره. (مورد هشتم در قسمت آپدیت مستندات). نوع اون آبجکت CallbackQuery هستش که میتونید ویژگی هاشو ببینید.

کار های مختلفی میشه کرد، من دو تا مثال رو اینجا میارم، ولی بقیش به عهده خلاقیت خودتونه.

کاربرد اول

ربات های [email protected] و [email protected] رو که دیدین؟ این ربات ها کارشون سادست. یک ورودی در دیتابیس خودشون برای هر رای‌گیری میسازن و فقط چند تا عدد درصدی رو توی اون سیو میکنن. نوع جواب دادنشون چیه؟ علاوه بر ویرایش پیام با متد editMessageText اگر دقت کرده باشید یه ناتیفیکیشن کوچیک بالای صفحه چت میاد که حاوی یک پیامه. این کار با متد answerCallbackQuery انجام میشه. این پیام رو هم فقط کاربری که کلید رو زده میبینه.

این یه نمونه خیلی ساده از مدل کاری یک رباته. بعد از هر callback تغییری توی دیتابیس ایجاد میشه و سپس پیام ویرایش میشه و یک پیام کوچیک هم برای کاربر میره. میتونید با این مدل که ربات مسابقه گروهی بسازید، خیلی باید جالب بشه!

مثال دوم

بعضی ربات ها نیاز به تنظیمات دارن. مثلا یک ربات مدیریت گروه. میشه یه منوی خیلی جذاب و زیبا با دکمه های اینلاین ساخت. هر ردیف دو کلید داره که یکی ورودی تنظیمات شما و روبروش مقدارشه. پس از هر callback اون تنظیمات توی دیتابیس تغییر میکنه و دوباره یک صفحه کلید مثل قبلی ولی اینبار با مقادیر جدید ساخته میشه و با متد editMessageReplyMarkup دوباره به همون پیام میچسبه.

تمرین

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

صفحه کلید های معمولی

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

 

حالت اینلاین

این حالت رو زیاد توضیح نمیدم. چون تا اینجا تا حد زیادی با قضیه آشنا شدید و مستندات تلگرام هم عالی توضیحشون داده.

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

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

وقتی هم که کاربر یک نتیجه رو انتخاب میکنه، مورد انتخابی به صورت chosen_inline_result داخل آپدیت دریافتی ظاهر میشه.

به ویژگی های هر کدوم از آبجکت های بالا دقت کنید، خیلی نیاز میشه!

جواب دادن به ورودی اینلاین

این کار با متد answerInlineQuery انجام میشه. ورودی های مختلفی میگیره ولی مهم ترینش نتیجه ای هست که کاربر دریافت میکنه. این نتیجه یا همون فیلد results درست مثل مثال قبلی صفحه کلید های شیشه ای باید در فرمت یک آبجکت JSON باشه. نوع هررکدوم هم میتونه یکی ۲۰ نوع InlineQueryResult که در مستندات API تعیین شده باشه.

مثال زیر رو ببینید:

فکر نکنم این مورد با توجه به مستندات توضیح خاصی نیاز داشته باشه. فقط این رو بدونید که نوع InlineQueryResult با توجه به ورودی type اون مشخص میشه. و نوع input_message_content هم با توجه به ورودی های خاص خودش. پس حتما به نوع ورودی ها در مستندات دقت کنید

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

کش کردن نتایج

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

سخن پایانی

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

 

امتیاز به این مطلب
Print Friendly, PDF & Email
سوشا
۲۰ سالمه و عاشق رایانه و گنو هستم... تمام سعیم اینه که مطالب آموزشی گنو رو تا اونجایی که در توانم هست بنویسم و در اختیار دیگران قرار بدم. آرزوم اینه که روزی یک سایت جامع برای آموزش گنو فراهم کنم :)
  • Muhammad Islampanah

    چرا سایتش بالا نمیاد؟

    • Sosha

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

      آها راستی، قرار به جای وبلاگش یک سایت جدیدی برای آموزش بیار بالا…