در جلسات قبل روش ایجاد ربات و روش های ارتباط با ربات تلگرام را بررسی کردیم، یکی از روش های ارتباط با ربات تلگرام ، فراخوانی متدهای API تلگرام بود، در این جلسه، متدهای مهمی از API تلگرام که برای ارتباط برنامه PHP ما با ربات کاربرد دارند را آموزش می دهیم.
متدهای ربات تلگرام برای ارسال اطلاعات بصورت زیر هستند:
sendMessage : ارسال پیام
forwardMessage : فوروارد کردن پیام
sendPhoto : ارسال تصویر
sendAudio : ارسال صدا
sendDocument : ارسال فایل
sendSticker : ارسال استیکر
sendVideo : ارسال فیلم
sendVoice : ارسال ویس
sendLocation : ارسال مکان
متد sendMessage
از این متد برای ارسال پیغام استفاده می شود و در صورت موفقیت آمیز بودن , پیغام ارسال شده برگشت داده می شود .
پارامترها :
- chat_id : آیدی منحصر به فرد یک کاربر یا کانال یا گروه که می توانید به جای آیدی از یوزرنیم به صورت channelusername@ استفاده کنید.
- text : متن پیامی که می خواهید ارسال کنید .
- parse_mode :اگر بخواهید متن هاتون رو به صورت bold, italic, fixed-width text or inline URLs یا به صورت Markdown ارسال کنید باید از این پارامتر استفاده کنید . اگر مقدار این پارامتر را html بگذارید می توانید متن html بفرستید و اگر Markdown بگذارید می توانید متن اتان را به صورت مارک دان ارسال کنید .
- disable_notification : اگر با false مقدار دهی شود پیام را بدون نمایش notification برای کاربر ارسال می کند
- reply_to_message_id :اگر می خواهید متنی که ارسال می کنید در جواب یک message دیگر باشد , آیدی آن را با استفاده از این پارامتر مشخص می کنید .
- reply_markup : این پارامتر برای اضافه کردن کیبورد دلخواه به ربات می باشد که کاربر با استفاده از این کیبورد و کلیدهای که ما ایجاد کردیم قادر به ارتباط به ربات باشد .
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<title>Untitled Document</title>
</head><body>
<?php
//$token='توکن مورد نظر شما';
//$chatId='آی دی کاربر یا گروه یا کانال مورد نظر';
//$text='متن پیغام مورد نظر';
$token="447175705:AAFrjrIIVEJQp9GbrFUvbfp54gYgyS0eIPY";
$chatId="@testch1300";
$text="hello";
$url = "https://api.telegram.org/bot$token/sendMessage?parse_mode=HTML&chat_id=$chatId&text=$text";
file_get_contents($url);
?>
</body>
</html>
در مثال بالا متد را sendMessage مشخص کردیم . api ربات را در متغیر token، آیدی کانال را در متغیر chatId و متن دلخواه را داخل متغیر text می نویسیم. با استفاده از این پارامترها url را می سازیم و در نهایت با استفاده از تابع file_get_contents درخواست را اجرا می کنیم.اگر خواستیم به جای متن html متن های مارک دان ارسال کنیم باید مقدار پارامتر parse_mode را Markdown قرار دهیم.
مثال : برنامه ریزی ربات برای اعلان تاریخ
برنامه زیر پیام های فرستاده شده در صفحه چت را خوانده و اگر شامل کلمه date بود، تاریخ سیستم را خوانده و به ربات می فرستد تا در صفحه چت نمایش داده شود. متد getUpdates هر 5 ثانیه یکبار فراخوانی شده است:
<?php
$token="447175705:AAFrjrIIVEJQp9GbrFUvbfp54gYgyS0eIPY";
$chat_id="@testch1300";
$last_updated_id=0;
while(true){
$last_updated_id++;
$url = "https://api.telegram.org/bot$token/getUpdates?offset=$last_updated_id";
$updates = json_decode(file_get_contents($url));
if($updates->ok == true && count($updates->result) > 0){
foreach($updates->result as $update){
$last_updated_id = $update->update_id;
$chat_id = $update->message->chat->id;
$message_id = $update->message->message_id;
$message_text = $update->message->text;
if ($message_text=="date") {
$date="date:".date("Y-m-d");
$url = "https://api.telegram.org/bot$token/sendMessage?parse_mode=HTML&chat_id=$chat_id&text=$date";
file_get_contents($url);
}
}
}else echo "Error";
sleep(5);
}
?>
متد forwardMessage
با استفاده از این متد می توانید یک متن برای برای فردی دیگر forward نمایید .
- chat_id :آیدی شخص یا گروهی که می خواهید پیغام برای آن forward شود .به جای آیدی از نام کاربری به صورت channelusername@ استفاده کنید.
- from_chat_id :آیدی شخص یا گروهی که پیغام شما در آن قرار دارد و میخواهید آن را forward کنید .به جای آیدی از نام کاربری به صورت channelusername@ استفاده کنید.
- disable_notification : اگر true باشد پیغام را به صورت Silent و بدون notification برای طرف ارسال می کند .
- message_id :آیدی پیام مورد نظر که قصد forward کردن آن را دارید.
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<title>Untitled Document</title>
</head>
<body>
<?php
//$token='توکن مورد نظر شما';
//$chatId='آی دی کاربر یا گروه یا کانال مورد نظر';
//$text='متن پیغام مورد نظر';
$token="447175705:AAFrjrIIVEJQp9GbrFUvbfp54gYgyS0eIPY";
$chatId="@testch1300";
$text="hello";
$url = "https://api.telegram.org/bot$token/forwardMessage?parse_mode=HTML&chat_id=$chatId&from_chat_id=$chatId&&message_id=800";
file_get_contents($url);
?>
</body>
</html>
ما در کد بالا را forwardMessage گذاشته و chat_id و from_chat_id را یکسان قرار دادیم برای اینکه یکی از پیغام های خودمان را که آیدی آن ۸۰۰ است را برای خودمان forward کنیم . شما می توانید درfrom_chat_id آیدی گروه یا شخص مورد نظر را بزنید تا پیغام برای او forward شود .
توجه داشته باشید که برای اجرای دو مثال فوق باید ربات عضو کانالی با آی دی مشخص بوده و از آی دی آن برای token استفاده کنیم.
متد sendPhoto
با استفاده از این متد می تواند در گروه ,کانال و یا یه شخص خاصی عکس ارسال نمایید .
- chat_id :آیدی شخص یا گروهی که می خواهید پیغام برای آن forward شود .به جای آیدی از یوزرنیم به صورت channelusername@ استفاده کنید.
- photo :عکسی که قصد ارسال آن را دارید . اگر این عکس قبلا در سرورهای تلگرام (Telegram)ذخیره شده می توانید آیدی آن را ارسال کنید و یا آن را دوباره آپلود نمایید .
- caption : می توانید برای عکس هایی که قبلن آپلود شده و file_id آن را دارید یک عنوان یاcaption قرار دهید . این عنوان می تواند ببین0-200 کاراکتر باشد.
- disable_notification :اگر true باشد پیغام را به صورت Silent و بدون notification برای طرف ارسال می کند .
- reply_to_message_id : اگر می خواهید عکسی که ارسال می کنید در جواب یک message دیگر باشد , آیدی آن را با استفاده از این پارامتر مشخص می کنید .
- reply_markup : این پارامتر برای اضافه کردن کیبورد دلخواه به ربات می باشد که کاربر با استفاده از این کیبورد و کلیدهای که ما ایجاد کردیم قادر به ارتباط به ربات باشد
متد sendAudio
این متد برای ارسال فایل های صوتی (audio files) می باشد . اگر می خواهید فایل ها در تلگرام کاربر پخش شود باید نوع آن Mp3باشد . در حال حاضر فایل صوتی می تواند تا حجم 50 MB باشد و ممکن است این محدودیت بعدن تغییر کند.
- chat_id :آیدی شخص یا گروهی که می خواهین پیغام برای آن forward شود .به جای آیدی از یوزرنیم به صورت channelusername@ استفاده کنید.
- audio :فایل صوتی که قصد ارسال آن را دارید . اگر این فایل قبلا در سرورهای تلگرام ذخیره شده می توانید آیدی (file_id ) آن را ارسال کنید و یا آن را دوباره آپلود نمایید
- duration :مدت زمان فایل صوتی به ثانیه
- performer :سازنده
- title :نام ترک
- disable_notification :اگر true باشد پیغام را به صورت Silent و بدون notification برای طرف ارسال می کند .
- reply_to_message_id : اگر می خواهید فایل صوتی که ارسال می کنید در جواب یک message دیگر باشد , آیدی آن را با استفاده از این پارامتر مشخص می کنید .
- reply_markup : این پارامتر برای اضافه کردن کیبورد دلخواه به ربات می باشد که کاربر با استفاده از این کیبورد و کلیدهای که ما ایجاد کردیم قادر به ارتباط به ربات باشد.
متد sendDocument
با استفاده از این متد می توانید فایل های عمومی را ارسال کنید . تقریبا همه نوع پسوند فایلی مجاز است و حداکثر حجم آن باید ۵۰ مگابایت باشد که ممکن است بعدا تغییر کند .
پارامترهای این متد دقیقا مانند پارامترهای قبلی است که توضیح داده شده .
متد sendSticker
از این متد می توانید برای ارسال استیکر استفاده کنید .
- sticker : استیکر مورد نظر است که می خواهید ارسال کنید . اگر این عکس قبلا در سرورهای تلگرام (Telegram) ذخیره شده می توانید آیدی آن را ارسال کنید و یا آن را دوباره آپلود نمایید .
- chat_id :آیدی شخص یا گروهی که می خواهین پیغام برای آن forward شود .به جای آیدی از یوزرنیم به صورت channelusername@ استفاده کنید.
- disable_notification :اگر true باشد پیغام را به صورت Silent و بدون notification برای طرف ارسال می کند .
- reply_to_message_id : اگر می خواهید فایل صوتی که ارسال می کنید در جواب یک message دیگر باشد , آیدی آن را با استفاده از این پارامتر مشخص می کنید .
- reply_markup : این پارامتر برای اضافه کردن کیبورد دلخواه به ربات می باشد که کاربر با استفاده از این کیبورد و کلیدهای که ما ایجاد کردیم قادر به ارتباط به ربات باشد.
متد sendVideo
از این متد می توانید برای ارسال فایل های ویدیویی استفاده کنید .فعلا تلگرام (Telegram) از فایل های ویدیویی با پسوند mp4 پشتیبانی می کند و حداکثر حجم آنها می تواند ۵۰ مگابایت باشد.
- chat_id :آیدی شخص یا گروهی که می خواهین پیغام برای آن forward شود .به جای آیدی از یوزرنیم به صورت channelusername@ استفاده کنید.
- video :فایل ویدیویی که قصد ارسال آن را دارید . اگر این فایل قبلا در سرورهای تلگرام ذخیره شده می توانید آیدی (file_id ) آن را ارسال کنید و یا آن را دوباره آپلود نمایید
- duration :مدت زمان فایل ویدیویی به ثانیه
- width :width فایل ویدیویی مورد نظر
- height : height فایل ویدیویی مورد نظر
- title :نام ترک
- disable_notification :اگر true باشد پیغام را به صورت Silent و بدون notification برای طرف ارسال می کند .
- reply_to_message_id : اگر می خواهید فایل صوتی که ارسال می کنید در جواب یک message دیگر باشد , آیدی آن را با استفاده از این پارامتر مشخص می کنید .
- reply_markup : این پارامتر برای اضافه کردن کیبورد دلخواه به ربات می باشد که کاربر با استفاده از این کیبورد و کلیدهای که ما ایجاد کردیم قادر به ارتباط به ربات باشد.
متد sendVoice
این متد هم برای ارسال فایل های صوتی (audio files ) می باشد . در واقع فایل هایی مد نظر هست که با گوشی ضبط شده و برای کاربر ارسال می کنیم .
توضیحات و پارامترهای این متد هم مانند متد sendAudio می باشد که بالاتر توضیح داده شده است .
متد sendLocation
از این متد برای ارسال یک نقطه روی نقشه می توانید استفاده کنید .
- chat_id :آیدی شخص یا گروهی که می خواهین پیغام برای آن forward شود .به جای آیدی از یوزرنیم به صورت channelusername@ استفاده کنید.
- latitude : عرض جغرافیایی مورد نظر
- longitude :طول جغرافیایی مورد نظر
- disable_notification :اگر true باشد پیغام را به صورت Silent و بدون notification برای طرف ارسال می کند .
- reply_to_message_id : اگر می خواهید فایل صوتی که ارسال می کنید در جواب یک message دیگر باشد , آیدی آن را با استفاده از این پارامتر مشخص می کنید .
- reply_markup : این پارامتر برای اضافه کردن کیبورد دلخواه به ربات می باشد که کاربر با استفاده از این کیبورد و کلیدهای که ما ایجاد کردیم قادر به ارتباط به ربات باشد.