🤖 راهنمای رسمی توسعه ربات‌های LI +

پرتال جامع مستندات فنی، نحوه ساخت ربات، دریافت توکن اختصاصی، اتصال با کتابخانه‌های پایتون، نودجی‌اس و گو به آدرس رسمی https://api.liplus.ir و پیاده‌سازی مینی‌اپ‌ها (Mini-Apps) بر روی بستر امن و پرسرعت LI +.

۱. ساخت ربات و دریافت توکن از طریق BotFather

تمامی ربات‌ها در پیام‌رسان LI + منحصراً از طریق ربات رسمی @BotFather ایجاد و مدیریت می‌شوند:

  1. در اپلیکیشن LI + ربات رسمی @BotFather را جستجو کرده و روی دکمه Start کلیک کنید.
  2. دستور /newbot را ارسال کنید تا فرآیند ساخت ربات جدید آغاز شود.
  3. نام نمایشی (Name): نام دلخواه ربات خود را بفرستید (مثلاً: فروشگاه آنلاین من).
  4. یوزرنیم یکتا (Username): یک شناسه انگلیسی منحصر‌به‌فرد که حتماً باید به کلمه bot ختم شود ارسال کنید (مثلاً: myshop_bot یا my_shop_bot).
  5. پس از تأیید، پیام حاوی توکن اختصاصی API (Bot Token) برای شما صادر می‌شود.
Bot Token Sample (HTTP API Access)
777100:AAFn1234567890abcdefghijklmnopqrstuv
حفظ امنیت توکن: توکن ربات شما کلید دسترسی به حساب ربات است. هرگز آن را در مخازن عمومی (Public Repositories) منتشر نکنید و برای امنیت بیشتر، توکن را در قالب متغیرهای محیطی (.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
ارتباط امن و بدون نیاز به پورت خاص: سرور API پیام‌رسان LI + با پورت استاندارد HTTPS در دسترس است، بنابراین ربات‌های شما از هر سرور، هاست لینوکس، ویندوز یا سرورهای بدون پورت اضافی به راحتی و با بیشترین سرعت متصل خواهند شد.

مشخصات پروتکل و فرمت پاسخ‌ها (JSON Response)

تمام پاسخ‌های ارسالی از سرور https://api.liplus.ir به فرمت استاندارد JSON و شامل فیلد ok هستند:

JSON Response Sample
{
  "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 تست و شبیه‌سازی کنید:

خروجی پاسخ سرور (JSON Result):
// برای آزمایش ارتباط روی دکمه "ارسال درخواست تست" کلیک کنید.

۳. نمونه کدهای آماده برای اتصال ربات

برای اتصال آسان، نمونه کدهای استاندارد و تست شده بر روی سرور رسمی https://api.liplus.ir به شرح زیر آماده شده است:

۱) پایتون با فریم‌ورک قدرتمند aiogram 3.x (پیشنهادی)

نصب کتابخانه‌های لازم:

Terminal / Bash
pip install aiogram aiohttp

فایل سورس کد bot.py:

Python (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

نصب کتابخانه:

Terminal / Bash
pip install python-telegram-bot

فایل سورس کد bot_ptb.py:

Python (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
npm install grammy

فایل سورس کد bot.js:

JavaScript (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 Package
go get gopkg.in/telebot.v3

فایل سورس کد main.go:

Go (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 (Vanilla / OOP)
<?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) از سمت سرور به وب‌سرور شما فرستاده شوند:

Python (aiogram Webhook)
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 (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 استفاده کنید:

Python (aiogram Mini-App)
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)

نمونه کد ساخت منوی تعاملی چندگزینه‌ای و پردازش کلیک کاربران:

Python (Inline Keyboards)
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 Process Manager
pm2 start bot.py --name my_liplus_bot --interpreter python3
# یا برای نودجی‌اس:
pm2 start bot.js --name my_liplus_node_bot

بررسی سریع صحت اتصال و دریافت اطلاعات هویتی ربات با دستور curl بر روی اندپوینت رسمی:

cURL Health Check (HTTPS)
curl https://api.liplus.ir/bot<BOT_TOKEN>/getMe