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

در این مقاله ضمن آموزش ساخت ربات و معرفی توابع مهم آن، یک پروژه کاربردی را بررسی می‌کنیم. ضمنا «هاست» یا میزبانی شما متاسفانه باید خارج از ایران باشد (هر چند ظاهرا راهکارهایی وجود دارد که من تجربه نکرده‌ام)

مراحل کار

الف) پیاده‌سازی ربات
ب) معرفی توابع مهم api تلگرام در php
ج) مثال کاربردی

الف) پیاده‌سازی ربات

جهت ساخت ربات تلگرام، لطفا لینک botFather را باز کرده و و روی گزینه Start کلیک کنید.

دستور /newbot: در بالا می‌توانید فهرستی از دستورات پیشفرض تلگرام را مشاهده نمایید. جهت ساخت اولین ربات خود دستور /newbot را انتخاب یا تایپ نمایید.

در گام بعدی از شما می‌خواهد یک «نام» یا name برای ربات خود در نظر بگیرید. نام مورد نظر خود را بنویسید. سپس می‌بایست «نام کاربری» یا username - که به «_bot» ختم می‌شود - را وارد نمایید. در صورت درستی اطلاعات پیامی حاوی «آدرس» و «توکن» ربات شما نمایش داده می‌شود. توکن را جایی ذخیره نمایید.

Done! Congratulations on your new bot. You will find it at t.me/<Your_Bot>_bot.
You can now add a description, about section and profile picture for your bot, see /help for a list of commands.
By the way, when you've finished creating your cool bot, ping our Bot Support if you want a better username for it.
Just make sure the bot is fully operational before you do this.

Use this token to access the HTTP API:
0000000000:XXXxxxxX0xXXxxXXxX0xxxxxx_xXX0x0Xxx
Keep your token secure and store it safely, it can be used by anyone to control your bot.

دستور /mybots: با اجرای این دستور فهرست ربات‌های شما نمایش داده می‌شود و ربات جدیدی که در بالا ساختید قابل نمایش است؛ روی آن کلیک کنید و در میان منوهای نمایش داده شده Edit Bot را انتخاب نمایید.

ویرایش Name: عنوان ربات که در ابتدای کار نوشته بودید قابل ویرایش است
ویرایش Description: به نوعی متن خوشآمد ورود به ربات شماست و یا راهنمایی که می‌توانید در شروع به کاربر نمایش دهید
ویرایش About: درباره ربات خود چند خطی بنویسید
ویرایش Botpic: تصویری مناسب برای ربات انتخاب کنید

تنظیم setWebhook: در پایان این مرحله، می‌بایست نشانی php صفحه‌ای از سایت خود را که قرار است با ربات تبادل اطلاعات داشته باشد تعریف نمایید.

https://api.telegram.org/bot<Your_API>/setWebhook?url=https://<Your_URL>

لطفا به جای <Your_API> و <Your_URL> مقدار توکن و نشانی صفحه مورد نظر سایت خود را نوشته و لینک را در مرورگر خود کپی و اجرا کنید.

ب) معرفی توابع مهم api تلگرام در php

در بالا و بخش setWebhook لینکی از سایت خود را تعریف کردیم که قرار بود با ربات ما تعامل داشته باشد. این صفحه php - که خود کدنویسی می‌کنیم - دو کار عمده انجام می‌دهد: نخست اطلاعاتی را از ربات دریافت می‌کند و سپس عملی انجام داده و در صورت نیاز پاسخی را بر می‌گرداند.

دریافت اطلاعات از ربات: هنگامی که کاربر در ربات تلگرام متن یا گزینه‌ای را وارد می‌کند، یک رشته از اطلاعات به سمت URL و صفحه php ما روانه می‌شود که توسط دستور زیر می‌توانیم به‌راحتی آن را دریافت کنیم:

<?php
$request = file_get_contents( 'php://input' );
?>

نمونه‌ای از رشته دریافتی از سمت ربات را می‌توانید در خطوط زیر مشاهده نمایید:

"update_id":<Update_ID>,
"message":{
	"message_id":5,
	"from":{
		"id":<From_ID>,
		"is_bot":false,
		"first_name":"Abdollah",
		"last_name":"Kaviani",
		"username":"abdollahkaviani",
		"language_code":"en"
	},
	"chat":{
		"id":<Chat_ID>,
		"first_name":"Abdollah",
		"last_name":"Kaviani",
		"username":"abdollahkaviani",
		"type":"private"
	},
	"date":1646994595,
	"text":"Test"
}

در خطوط بالا بیشتر با دو پارامتر Chat_ID (شناسه کاربر) و مقدار text (متن پیام) کار داریم و از این پس با دانستن «شناسه کاربر» می‌توانیم برای وی پیام ارسال کرده و یا کاربر را بشناسیم البته به شرط آن که ربات ما را Delete نکند!

ارسال اطلاعات به ربات: برای ارسال اطلاعات از صفحه php سایت خود به ربات، تابعی به نام sendToTelegram ایجاد و سپس پارامترهای آن را بررسی می‌کنیم. لطفا به جای <Your_API> در تابع زیر توکن خود را جایگذاری کنید:

<?php
function sendToTelegram($method, $parameters=[]) {

	$handle = curl_init("https://api.telegram.org/bot<Your_API>/$method");
	curl_setopt($handle, CURLOPT_RETURNTRANSFER, true);
	curl_setopt($handle, CURLOPT_POSTFIELDS, json_encode($parameters));
	curl_setopt($handle, CURLOPT_HTTPHEADER, array("Content-Type: application/json"));
	$result = curl_exec($handle);
	return $result;
}
?>

تابع sendToTelegram دو متغیر نیاز دارد. به عنوان مثال چنانچه بخواهیم در پاسخ به درخواست کاربر «متنی» برای وی ارسال کنیم به شکل زیر عمل می‌نماییم. توجه کنید که مقدار chat_id همان مقداری است که از سمت کاربر دریافت کرده‌ایم. سپس توسط متد sendMessage متن «سلام» را برای وی ارسال نموده‌ایم:

<?php
$parameters = [
	"chat_id" 	=> <Chat_ID>,
	"text" 	=> "سلام"
];
$method = 'sendMessage';
echo sendToTelegram($method, $parameters);
?>

چنانچه بخواهیم به جای متن یک تصویر برای کاربر ارسال کنیم به این شکل عمل می‌کنیم:

<?php
$parameters = [
	"chat_id"	=> <Chat_ID>,
	"photo"	=> "https://abdollahkaviani.ir/images/logo.png",
	"caption" 	=> 'AK'
];
$method = 'sendPhoto';
echo sendToTelegram($method, $parameters);
?>

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

ج) مثال کاربردی

با فرض اینکه قسمت «الف» این مقاله را - که پیاده‌سازی ربات باشد - به درستی انجام داده باشید، مثال زیر را بررسی می‌کنیم. در این مثال قصد داریم به عنوان صاحب یک فروشگاه اینترنتی، موجودی کالای سایت خود را - از طریق ربات تلگرام - مشاهده کنیم. لطفا به جای <Your_API> در تابع sendToTelegram توکن خود را جایگذاری کنید:

<?php
$request 	= file_get_contents( 'php://input' );
$request 	= json_decode( $request, TRUE );

if(isset($request['update_id'])) {
	
	$subMenu 	= $request['callback_query']['data'];
	
	//Menu
	if($subMenu) {
		
		$chatId	= $request['callback_query']['message']['chat']['id'];

		switch ($subMenu) {
				
			case '/book':
				$parameters = [
					"chat_id" => $chatId,
					"text" => "6 عدد"
				];
				break;
			case '/mobile':
				$parameters = [
					"chat_id" => $chatId,
					"text" => "4 عدد"
				];
				break;
			default:
				$parameters = [
					"chat_id" => $chatId,
					"text" => "تعریف نشده!"
				];
		}
		
		echo sendToTelegram('sendMessage', $parameters);		
	} 
	//Commands
	else {
		
		$chatId  		= $request['message']['chat']['id'];
		$message 	= $request['message']['text'];

		switch ($message) {
			case "/Start":
			case "/start":
				$parameters = [
					"chat_id" => $chatId,
					"text" => "کالاهای موجود سایت",
					"reply_markup" => array(
						"inline_keyboard" => array(
							array(
								array("text" => "کتاب", "callback_data" => "/book"),
								array("text" => "موبایل", "callback_data" => "/mobile"),
								array("text" => "راهنما", "url" => "https://abdollahkaviani.ir/article?number=14")			
							)
						)
					)
				];
				break;
			default:
				$parameters = [
					"chat_id" => $chatId,
					"text" => "تعریف نشده!"
				];
		} 
		
		echo sendToTelegram('sendMessage', $parameters);
	}
}

function sendToTelegram($method, $parameters=[]) {

	$handle = curl_init("https://api.telegram.org/bot<Your_API>/$method");
	curl_setopt($handle, CURLOPT_RETURNTRANSFER, true);
	curl_setopt($handle, CURLOPT_POSTFIELDS, json_encode($parameters));
	curl_setopt($handle, CURLOPT_HTTPHEADER, array("Content-Type: application/json"));
	$result = curl_exec($handle);
	return $result;
}
?>

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