🤖 راهنمای رسمی توسعه رباتهای LI +
پرتال جامع مستندات فنی، نحوه ساخت ربات، دریافت توکن اختصاصی، اتصال با کتابخانههای پایتون، نودجیاس و گو به آدرس رسمی https://api.liplus.ir و پیادهسازی مینیاپها (Mini-Apps) بر روی بستر امن و پرسرعت LI +.
۱. ساخت ربات و دریافت توکن از طریق BotFather
تمامی رباتها در پیامرسان LI + منحصراً از طریق ربات رسمی @BotFather ایجاد و مدیریت میشوند:
-
در اپلیکیشن LI + ربات رسمی
@BotFatherرا جستجو کرده و روی دکمه Start کلیک کنید. -
دستور
/newbotرا ارسال کنید تا فرآیند ساخت ربات جدید آغاز شود. -
نام نمایشی (Name): نام دلخواه ربات خود را بفرستید (مثلاً:
فروشگاه آنلاین من). -
یوزرنیم یکتا (Username): یک شناسه انگلیسی منحصربهفرد که حتماً باید به کلمه
botختم شود ارسال کنید (مثلاً:myshop_botیاmy_shop_bot). - پس از تأیید، پیام حاوی توکن اختصاصی API (Bot Token) برای شما صادر میشود.
777100:AAFn1234567890abcdefghijklmnopqrstuv
.env) نگهداری نمایید.
دستورات کاربردی BotFather برای مدیریت ربات
| دستور | کاربرد و عملکرد |
|---|---|
/mybots |
مشاهده لیست رباتها، تنظیمات پیشرفته و دریافت مجدد توکن |
/setdescription |
تنظیم متن معرفی قبل از استارت ربات |
/setabouttext |
تنظیم بخش درباره ربات (About) در پروفایل |
/setuserpic |
تغییر عکس و آواتار پروفایل ربات |
/setcommands |
تنظیم لیست دستورات و دکمه منوی منو در چت (Bot Menu Commands) |
/token |
تولید مجدد یا باطل کردن توکن فعلی (Revoke Token) |
۲. آدرس رسمی و عمومی Bot API سرور
کلیه ارتباطات و درخواستهای توسعهدهندگان باید به آدرس عمومی، امن و رمزنگاریشده زیر ارسال شوند:
| پارامتر | مقدار رسمی و استاندارد | توضیحات و امنیت |
|---|---|---|
| آدرس Base URL عمومی: | https://api.liplus.ir |
اندپوینت رسمی با پایداری ۹۹.۹٪ و مانیتورینگ خودکار |
| پروتکل امنیتی: | HTTPS (SSL / TLS 1.3) |
پورت استاندارد ۴۴۳ با رمزنگاری سرتاسری ترافیک |
| فرمت فراخوانی متدها: | https://api.liplus.ir/bot<TOKEN>/<METHOD> |
سازگاری کامل و ۱۰۰٪ با استاندارد Telegram Bot API |
مشخصات پروتکل و فرمت پاسخها (JSON Response)
تمام پاسخهای ارسالی از سرور https://api.liplus.ir به فرمت استاندارد JSON و شامل فیلد ok هستند:
{
"ok": true,
"result": {
"id": 777100,
"is_bot": true,
"first_name": "فروشگاه Liplus",
"username": "liplus_shop_bot",
"can_join_groups": true,
"can_read_all_group_messages": false,
"supports_inline_queries": false
}
}
کنسول زنده تست آنلاین متدهای Bot API
با استفاده از کنسول زیر میتوانید بدون نیاز به نصب هیچگونه ابزاری، متدهای مختلف را بر روی سرور رسمی https://api.liplus.ir تست و شبیهسازی کنید:
// برای آزمایش ارتباط روی دکمه "ارسال درخواست تست" کلیک کنید.
۳. نمونه کدهای آماده برای اتصال ربات
برای اتصال آسان، نمونه کدهای استاندارد و تست شده بر روی سرور رسمی https://api.liplus.ir به شرح زیر آماده شده است:
۱) پایتون با فریمورک قدرتمند aiogram 3.x (پیشنهادی)
نصب کتابخانههای لازم:
pip install aiogram aiohttp
فایل سورس کد bot.py:
import asyncio
from aiogram import Bot, Dispatcher, types
from aiogram.client.session.aiohttp import AiohttpSession
from aiogram.client.telegram import TelegramAPIServer
from aiogram.filters import CommandStart
BOT_TOKEN = "777100:AAFn1234567890abcdefghijklmnopqrstuv"
# اتصال به اندپوینت رسمی LI +:
SERVER_URL = "https://api.liplus.ir"
async def main():
session = AiohttpSession(
api=TelegramAPIServer.from_base(SERVER_URL)
)
bot = Bot(token=BOT_TOKEN, session=session)
dp = Dispatcher()
@dp.message(CommandStart())
async def handle_start(message: types.Message):
await message.answer(
f"سلام {message.from_user.first_name} عزیز! 🌟\nبه ربات اختصاصی LI + خوش آمدید."
)
@dp.message()
async def echo_handler(message: types.Message):
await message.answer(f"پیام شما: {message.text}")
print("🤖 Bot started polling via https://api.liplus.ir...")
await dp.start_polling(bot)
if __name__ == "__main__":
asyncio.run(main())
۲) پایتون با python-telegram-bot
نصب کتابخانه:
pip install python-telegram-bot
فایل سورس کد bot_ptb.py:
from telegram import Update
from telegram.ext import ApplicationBuilder, CommandHandler, MessageHandler, filters, ContextTypes
BOT_TOKEN = "777100:AAFn1234567890abcdefghijklmnopqrstuv"
# برای کتابخانه PTB آدرس با /bot خاتمه مییابد:
BASE_URL = "https://api.liplus.ir/bot"
async def start(update: Update, context: ContextTypes.DEFAULT_TYPE):
await update.message.reply_text("سلام! ربات آنلاین است.")
async def echo(update: Update, context: ContextTypes.DEFAULT_TYPE):
await update.message.reply_text(update.message.text)
if __name__ == '__main__':
app = ApplicationBuilder().token(BOT_TOKEN).base_url(BASE_URL).build()
app.add_handler(CommandHandler("start", start))
app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, echo))
print("🤖 Python-Telegram-Bot is running on https://api.liplus.ir...")
app.run_polling()
۳) جاوااسکریپت و تایپاسکریپت با grammY (Node.js)
نصب کتابخانه با npm:
npm install grammy
فایل سورس کد bot.js:
const { Bot } = require("grammy");
const bot = new Bot("777100:AAFn1234567890abcdefghijklmnopqrstuv", {
client: {
// تنظیم آدرس رسمی API سرور:
apiRoot: "https://api.liplus.ir",
},
});
// پاسخ به دستور /start
bot.command("start", async (ctx) => {
await ctx.reply(`درود ${ctx.from.first_name}! ربات فعال است 🚀`);
});
// پاسخ به تمامی پیامهای متنی
bot.on("message:text", async (ctx) => {
await ctx.reply(`شما فرستادید: ${ctx.message.text}`);
});
bot.start();
console.log("🤖 grammY bot is running on https://api.liplus.ir...");
۴) زبان گو (Golang با کتابخانه Telebot v3)
نصب پکیج با go get:
go get gopkg.in/telebot.v3
فایل سورس کد main.go:
package main
import (
"log"
"time"
tele "gopkg.in/telebot.v3"
)
func main() {
pref := tele.Settings{
Token: "777100:AAFn1234567890abcdefghijklmnopqrstuv",
URL: "https://api.liplus.ir", // آدرس رسمی سرور
Poller: &tele.LongPoller{Timeout: 10 * time.Second},
}
b, err := tele.NewBot(pref)
if err != nil {
log.Fatal(err)
}
b.Handle("/start", func(c tele.Context) error {
return c.Send("سلام! ربات نوشته شده با Go فعال است.")
})
b.Handle(tele.OnText, func(c tele.Context) error {
return c.Send("اکو: " + c.Text())
})
log.Println("🤖 Go bot is running on https://api.liplus.ir...")
b.Start()
}
۵) زبان پیاچپی (PHP cURL & Helper Class)
پیادهسازی سریع با cURL خالص بدون نیاز به نصب هیچگونه کتابخانه خارجی (فایل api/bot_helper.php):
<?php
require_once __DIR__ . '/api/bot_helper.php';
$botToken = '777100:AAFn1234567890abcdefghijklmnopqrstuv';
$bot = new LiplusBot($botToken);
// ارسال پیام به چت کاربر
$bot->sendMessage(777009, "سلام! ربات توسعه داده شده با PHP فعال است 🚀", [
'reply_markup' => [
'inline_keyboard' => [
[
['text' => '🚀 باز کردن مینیاپ', 'web_app' => ['url' => 'https://app.liplus.ir']],
['text' => '💎 خرید اشتراک', 'callback_data' => 'buy_sub']
]
]
]
]);
۴. اجرای ربات در حالت وبهوک (Webhook Mode)
اگر میخواهید آپدیتها و پیامها بدون نیاز به Polling و به شکل فوری (Push Notification) از سمت سرور به وبسرور شما فرستاده شوند:
from aiogram import Bot, Dispatcher
from aiogram.client.session.aiohttp import AiohttpSession
from aiogram.client.telegram import TelegramAPIServer
from aiohttp import web
BOT_TOKEN = "777100:AAFn1234567890abcdefghijklmnopqrstuv"
WEBHOOK_URL = "https://your-domain.com/webhook"
SECRET_TOKEN = "my_secret_token_123"
session = AiohttpSession(api=TelegramAPIServer.from_base("https://api.liplus.ir"))
bot = Bot(token=BOT_TOKEN, session=session)
dp = Dispatcher()
async def on_startup(app):
await bot.set_webhook(
url=WEBHOOK_URL,
secret_token=SECRET_TOKEN,
drop_pending_updates=True
)
نمونه دریافت وبهوک با زبان PHP (فایل api/webhook.php):
<?php
require_once __DIR__ . '/bot_helper.php';
$bot = new LiplusBot('777100:AAFn1234567890abcdefghijklmnopqrstuv');
$update = json_decode(file_get_contents('php://input'), true);
if (isset($update['message'])) {
$chatId = $update['message']['chat']['id'];
$text = $update['message']['text'] ?? '';
if ($text === '/start') {
$bot->sendMessage($chatId, "سلام! وبهوک PHP با موفقیت فعال شد.");
}
}
۵. راهاندازی مینیاپ و وباپ در ربات (Mini-Apps / WebApps)
برای باز کردن یک صفحه وب یا فروشگاه درون اپلیکیشن LI + با کلیک کاربر بر روی دکمه شیشهای، از آبجکت WebAppInfo استفاده کنید:
from aiogram.types import InlineKeyboardMarkup, InlineKeyboardButton, WebAppInfo
@dp.message(CommandStart())
async def send_miniapp(message: types.Message):
keyboard = InlineKeyboardMarkup(
inline_keyboard=[
[
InlineKeyboardButton(
text="🚀 باز کردن مینیاپ",
web_app=WebAppInfo(url="https://app.liplus.ir")
)
]
]
)
await message.answer("برای ورود به اپلیکیشن روی دکمه زیر کلیک کنید:", reply_markup=keyboard)
۶. دکمههای شیشهای و اینلاین (Inline Keyboards & Callbacks)
نمونه کد ساخت منوی تعاملی چندگزینهای و پردازش کلیک کاربران:
from aiogram.types import InlineKeyboardMarkup, InlineKeyboardButton
@dp.message(Command("menu"))
async def show_menu(message: types.Message):
keyboard = InlineKeyboardMarkup(
inline_keyboard=[
[
InlineKeyboardButton(text="💎 خرید اشتراک", callback_data="buy_sub"),
InlineKeyboardButton(text="📞 پشتیبانی", callback_data="support"),
],
[
InlineKeyboardButton(text="🌐 مشاهده وبسایت", url="https://liplus.ir")
]
]
)
await message.answer("منوی دسترسی سریع:", reply_markup=keyboard)
@dp.callback_query(lambda c: c.data == 'buy_sub')
async def process_callback(callback_query: types.CallbackQuery):
await callback_query.answer("در حال انتقال به درگاه پرداخت...")
await callback_query.message.answer("لینک پرداخت برای شما ارسال شد.")
۷. استقرار در پسزمینه و بررسی سلامت ربات
برای پایدار نگه داشتن ربات در سرور لینوکس میتوانید از ابزار pm2 استفاده کنید:
pm2 start bot.py --name my_liplus_bot --interpreter python3
# یا برای نودجیاس:
pm2 start bot.js --name my_liplus_node_bot
بررسی سریع صحت اتصال و دریافت اطلاعات هویتی ربات با دستور curl بر روی اندپوینت رسمی:
curl https://api.liplus.ir/bot<BOT_TOKEN>/getMe