آموزش ساخت ربات تلگرام بدون سرور (Telegram Serverless)

Telegram Serverless چیست؟

Telegram Serverless یک محیط اجرای ابری برای بک‌اند ربات‌ها و Mini Appهای تلگرام است. در این روش، توسعه‌دهنده به‌جای اجاره سرور و اجرای دائمی برنامه، فایل‌های JavaScript پروژه را روی زیرساخت تلگرام منتشر می‌کند. هر زمان یک رویداد مانند پیام جدید، فشردن دکمه، Inline Query یا درخواست عضویت اتفاق بیفتد، تلگرام Handler مربوط به آن رویداد را اجرا می‌کند.

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

ربات تلگرام قبلاً چگونه کار می‌کرد؟

در روش سنتی، پس از ساخت ربات در BotFather باید یک برنامه PHP، Python، JavaScript یا زبان دیگری روی هاست یا VPS اجرا می‌کردید. سپس ربات به یکی از دو روش پیام‌ها را دریافت می‌کرد:

• Long Polling: برنامه به‌طور مرتب با متد getUpdates از تلگرام درخواست دریافت پیام‌های جدید می‌کرد.
• Webhook: تلگرام هر پیام جدید را به یک آدرس HTTPS روی سرور توسعه‌دهنده ارسال می‌کرد.

در هر دو روش، مسئولیت روشن‌ماندن سرور، تنظیم SSL، مدیریت خطاها، امنیت، مصرف منابع، ثبت گزارش‌ها و مقیاس‌دهی ربات بر عهده توسعه‌دهنده بود. مستندات رسمی Bot API نیز Webhook و getUpdates را دو روش اصلی و غیرهم‌زمان دریافت Update معرفی می‌کند.

با Telegram Serverless، بخش دریافت رویدادها و اجرای Handlerها توسط خود تلگرام انجام می‌شود. بنابراین برای بسیاری از ربات‌های سبک و متوسط، دیگر لازم نیست یک سرور عمومی همیشه روشن داشته باشید.

اطلاعات کامل متدها و ساختار Updateها در مستندات رسمی Telegram Bot API قرار دارد.

مزایای ساخت ربات تلگرام بدون سرور

۱. حذف هزینه اولیه هاست و VPS

برای ساخت یک ربات ساده دیگر مجبور نیستید در همان ابتدای کار سرور تهیه کنید. این موضوع برای پروژه‌های آزمایشی، ربات‌های شخصی، ابزارهای کوچک، مسابقه‌ها و MVPها اهمیت زیادی دارد.

۲. حذف تنظیم دستی Webhook

در این سرویس، Webhook توسط پلتفرم مدیریت می‌شود. با اضافه یا حذف‌کردن Handlerها می‌توانید وضعیت Webhook را همگام کنید و لازم نیست آدرس مستقلی را با متد setWebhook ثبت کنید.

۳. دیتابیس داخلی

Telegram Serverless یک دیتابیس مبتنی بر SQLite و ابزار Query Builder در اختیار پروژه می‌گذارد. به کمک آن می‌توان اطلاعات کاربران، وضعیت گفتگو، امتیازها، تنظیمات و داده‌های سبک را بین اجراهای مختلف حفظ کرد.

۴. مقیاس‌دهی خودکار

در ربات‌های معمولی، افزایش ناگهانی تعداد کاربران ممکن است باعث پرشدن منابع هاست یا کندشدن پردازش شود. در معماری Serverless اجرای کد بر اساس رویداد انجام می‌شود و مدیریت زیرساخت بر عهده ارائه‌دهنده است.

۵. دسترسی مستقیم به Bot API

SDK داخلی سرویس امکان فراخوانی متدهای Bot API مانند sendMessage، editMessageText و answerCallbackQuery را بدون واردکردن دوباره توکن Bot API در هر درخواست فراهم می‌کند.

۶. امکان اتصال به سرویس‌های خارجی

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

پیش‌نیازهای شروع کار

برای اجرای آموزش این مقاله به موارد زیر نیاز دارید:

• یک حساب فعال تلگرام
• یک ربات ساخته‌شده با BotFather
• نصب Node.js نسخه ۱۸ یا بالاتر
• آشنایی مقدماتی با JavaScript
• دسترسی به Terminal، PowerShell یا Command Prompt

برخلاف بسیاری از آموزش‌های قدیمی، در این روش به دامنه، SSL، cPanel، هاست PHP یا IP ثابت نیاز ندارید.

فعال‌سازی Telegram Serverless در BotFather

ابتدا وارد ربات رسمی BotFather شوید و مراحل زیر را انجام دهید:

1. گفتگو با @BotFather را باز کنید.
2. از منوی مدیریت، ربات موردنظر خود را انتخاب کنید.
3. گزینه Serverless را باز کنید.
4. قابلیت Serverless را برای ربات روشن کنید.
5. وارد بخش CLI Access شوید.
6. یک Access Token مخصوص CLI دریافت کنید.

توکن CLI برای اتصال پروژه محلی به محیط ابری تلگرام استفاده می‌شود و معمولاً ساختاری شبیه app<id>:<secret> دارد.

ساخت پروژه Telegram Serverless

Terminal را باز کنید و دستور زیر را اجرا کنید:

npm create @tgcloud/bot my-telegram-bot
```

cd my-telegram-bot

این دستور یک پروژه آماده با فایل‌ها و پوشه‌های موردنیاز ایجاد می‌کند. نام my-telegram-bot دلخواه است و می‌توانید آن را تغییر دهید.

سپس پروژه را به ربات خود متصل کنید:

npx tgcloud login

در این مرحله از شما Access Token دریافت‌شده از BotFather خواسته می‌شود. پس از ورود موفق، اطلاعات اتصال در پوشه محلی .tgcloud نگهداری می‌شود.

برای مشاهده وضعیت پروژه دستور زیر را اجرا کنید:

npx tgcloud status

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

npx tgcloud diff

ساخت اولین ربات پاسخ‌گو

در Telegram Serverless هر نوع Update می‌تواند Handler مخصوص خودش را داشته باشد. برای مدیریت پیام‌های عادی، فایل زیر اجرا می‌شود:

handlers/message.js

محتوای فایل را به شکل زیر قرار دهید:

import { api } from 'sdk';
```

export default async function (message) {
const chatId = message.chat.id;
const text = message.text || '';

```
await api.sendMessage({
    chat_id: chatId,
    text: `سلام! پیام شما دریافت شد:\n\n${text}`
});
```

}

تابع Exportشده هنگام دریافت پیام اجرا می‌شود. شیء message همان اطلاعات پیام تلگرام، شامل شناسه گفتگو، متن، فرستنده و سایر جزئیات است.

متد api.sendMessage مستقیماً از SDK تلگرام فراخوانی می‌شود. به همین دلیل نیازی نیست آدرس api.telegram.org یا توکن ربات را به‌صورت دستی در کد قرار دهید.

مدیریت دستورهای /start و /help

در یک ربات واقعی معمولاً نمی‌خواهیم به تمام پیام‌ها پاسخ یکسان بدهیم. نمونه زیر دستورهای /start و /help را جداگانه مدیریت می‌کند:

import { api } from 'sdk';
```

export default async function (message) {
const chatId = message.chat.id;
const text = (message.text || '').trim();

```
if (text === '/start') {
    await api.sendMessage({
        chat_id: chatId,
        text:
            'سلام! به ربات نمونه خوش آمدید.\n\n' +
            'برای مشاهده راهنما دستور /help را ارسال کنید.'
    });

    return;
}

if (text === '/help') {
    await api.sendMessage({
        chat_id: chatId,
        text:
            'راهنمای ربات:\n\n' +
            '/start - شروع کار\n' +
            '/help - نمایش راهنما\n' +
            '/about - درباره ربات'
    });

    return;
}

if (text === '/about') {
    await api.sendMessage({
        chat_id: chatId,
        text: 'این ربات با Telegram Serverless ساخته شده است.'
    });

    return;
}

await api.sendMessage({
    chat_id: chatId,
    text: 'دستور واردشده را متوجه نشدم. از /help استفاده کنید.'
});
```

}

در پروژه‌های بزرگ‌تر بهتر است منطق دستورها را در فایل‌های جداگانه داخل پوشه lib نگهداری کنید تا Handler اصلی بیش از حد طولانی نشود.

ساخت دکمه شیشه‌ای در ربات

دکمه‌های Inline یکی از پرکاربردترین بخش‌های ربات تلگرام هستند. در نمونه زیر، کاربر پس از اجرای دستور /start دو دکمه مشاهده می‌کند:

import { api } from 'sdk';
```

export default async function (message) {
const chatId = message.chat.id;
const text = (message.text || '').trim();

```
if (text !== '/start') {
    return;
}

await api.sendMessage({
    chat_id: chatId,
    text: 'یکی از گزینه‌های زیر را انتخاب کنید:',
    reply_markup: {
        inline_keyboard: [
            [
                {
                    text: 'مشاهده خدمات',
                    callback_data: 'show_services'
                }
            ],
            [
                {
                    text: 'ورود به پرمیوم فارسی',
                    url: 'https://fapremium.ir/'
                }
            ]
        ]
    }
});
```

}

“`

دکمه اول یک Callback ایجاد می‌کند و باید در Handler مربوط به callback_query پردازش شود. دکمه دوم کاربر را به وب‌سایت پرمیوم فارسی هدایت می‌کند.

برای مدیریت کلیک دکمه اول، فایل زیر را بسازید:

handlers/callback_query.js

سپس این کد را در آن قرار دهید:

import { api } from 'sdk';
```

export default async function (callbackQuery) {
const data = callbackQuery.data;
const chatId = callbackQuery.message?.chat?.id;

```
await api.answerCallbackQuery({
    callback_query_id: callbackQuery.id
});

if (!chatId) {
    return;
}

if (data === 'show_services') {
    await api.sendMessage({
        chat_id: chatId,
        text:
            'خدمات قابل ارائه:\n\n' +
            '• تلگرام پرمیوم\n' +
            '• تلگرام استارز\n' +
            '• بوست کانال تلگرام\n' +
            '• سرویس‌های دیجیتال'
    });
}
```

}

اجرای answerCallbackQuery اهمیت دارد؛ زیرا باعث می‌شود حالت در حال بارگذاری دکمه در برنامه تلگرام متوقف شود.

ذخیره اطلاعات کاربران در دیتابیس داخلی

یکی از تفاوت‌های مهم Telegram Serverless با یک تابع ساده ابری، دیتابیس داخلی آن است. برای نمونه می‌توانیم تعداد پیام‌های هر کاربر را ذخیره کنیم.

ابتدا فایل schema.js را ویرایش کنید:

import { table, integer, text } from 'sdk/db';
```

export const users = table('users', {
userId: integer('user_id').primaryKey(),
firstName: text('first_name'),
username: text('username'),
messageCount: integer('message_count').notNull().default(0)
});

سپس Handler پیام را به شکل زیر تغییر دهید:

import { api, db } from 'sdk';
```

import { sql } from 'sdk/db';
import { users } from 'schema';

export default async function (message) {
const chatId = message.chat.id;
const user = message.from;

```
if (!user) {
    return;
}

const [savedUser] = await db
    .insert(users)
    .values({
        userId: user.id,
        firstName: user.first_name || '',
        username: user.username || '',
        messageCount: 1
    })
    .onConflictDoUpdate({
        target: users.userId,
        set: {
            firstName: user.first_name || '',
            username: user.username || '',
            messageCount: sql`${users.messageCount} + 1`
        }
    })
    .returning()
    .run();

await api.sendMessage({
    chat_id: chatId,
    text: `سلام ${savedUser.firstName}، تاکنون ${savedUser.messageCount} پیام برای من فرستاده‌اید.`
});
```

}

پس از تغییر Schema، فقط انتشار فایل‌ها کافی نیست و باید Migration دیتابیس را نیز اجرا کنید:

npx tgcloud push
```

npx tgcloud migrate

دستور push ماژول‌ها را منتشر می‌کند و دستور migrate تغییرات تعریف‌شده در Schema را روی دیتابیس اعمال می‌کند.

اتصال ربات Serverless به API خارجی

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

در Telegram Serverless می‌توان از fetch موجود در SDK استفاده کرد:

import { api, fetch } from 'sdk';
```

export default async function (message) {
const chatId = message.chat.id;
const text = (message.text || '').trim();

```
if (!text.startsWith('/order ')) {
    return;
}

const orderCode = text.replace('/order ', '').trim();

if (!/^[0-9]{4,20}$/.test(orderCode)) {
    await api.sendMessage({
        chat_id: chatId,
        text: 'کد سفارش معتبر نیست.'
    });

    return;
}

try {
    const response = await fetch(
        `https://example.com/api/orders/${orderCode}`,
        {
            method: 'GET',
            headers: {
                Accept: 'application/json'
            }
        }
    );

    if (!response.ok) {
        throw new Error(`API error: ${response.status}`);
    }

    const result = await response.json();

    await api.sendMessage({
        chat_id: chatId,
        text:
            `وضعیت سفارش ${orderCode}:\n\n` +
            `محصول: ${result.product}\n` +
            `وضعیت: ${result.status}`
    });
} catch (error) {
    console.error('Order API failed', error);

    await api.sendMessage({
        chat_id: chatId,
        text: 'در حال حاضر دریافت وضعیت سفارش ممکن نیست. کمی بعد دوباره تلاش کنید.'
    });
}
```

}

در پروژه واقعی نباید اطلاعات حساس سفارش صرفاً با دانستن کد سفارش نمایش داده شود. بهتر است مالکیت سفارش با شناسه تلگرام، شماره موبایل، توکن یک‌بارمصرف یا امضای امن API بررسی شود.

نمونه ارسال درخواست POST

import { fetch } from 'sdk';
```

const response = await fetch('https://example.com/api/tickets', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Accept: 'application/json'
},
body: JSON.stringify({
telegram_user_id: 123456789,
subject: 'درخواست پشتیبانی',
message: 'پیام آزمایشی کاربر'
})
});

if (!response.ok) {
throw new Error(`Request failed: ${response.status}`);
}

const result = await response.json();

“`

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

ساختار فایل‌های پروژه Telegram Serverless

ساختار پایه پروژه معمولاً به شکل زیر است:

my-telegram-bot/
```

├── handlers/
│   ├── message.js
│   └── callback_query.js
├── lib/
│   ├── validation.js
│   ├── messages.js
│   └── api-client.js
├── docs/
├── schema.js
├── package.json
├── AGENTS.md
└── .tgcloud/

پوشه handlers

فایل‌های ورودی رویدادهای تلگرام در این پوشه قرار می‌گیرند. نام هر Handler بر اساس نوع Update انتخاب می‌شود؛ مانند:

• message.js برای پیام‌های جدید
• callback_query.js برای کلیک روی دکمه‌ها
• inline_query.js برای درخواست‌های Inline
• chat_join_request.js برای درخواست عضویت

پوشه lib

کدهای مشترک مانند اعتبارسنجی، ساخت متن پیام، ارتباط با API و توابع کمکی بهتر است در این پوشه قرار بگیرند.

فایل schema.js

جدول‌ها و ستون‌های دیتابیس داخلی پروژه در این فایل تعریف می‌شوند. تغییر این فایل نیازمند اجرای Migration است.

تست ربات قبل از انتشار

برای تست Handler بدون انتشار عمومی می‌توانید از دستور run استفاده کنید:

npx tgcloud run handlers/message '{ chat: { id: 1 }, text: "hello" }'

این دستور Handler را با داده آزمایشی روی پلتفرم اجرا می‌کند و خروجی Console، زمان اجرا و خطاهای احتمالی را نمایش می‌دهد.

برای ثبت گزارش نیز می‌توانید از Console استفاده کنید:

console.log('Message received', {
chatId: message.chat.id,
text: message.text
```

});

console.warn('Invalid command');

console.error('External API failed', error);

انتشار نسخه نهایی

پس از تکمیل تغییرات، کد را منتشر کنید:

npx tgcloud push

اگر Schema دیتابیس تغییر کرده است:

npx tgcloud migrate

برای بررسی وضعیت Webhook:

npx tgcloud webhook

برای همگام‌سازی Webhook با Handlerهای منتشرشده:

npx tgcloud webhook sync

محدودیت‌های Telegram Serverless

با وجود جذاب‌بودن این قابلیت، Telegram Serverless جایگزین کامل همه سرورها نیست. پیش از انتقال یک پروژه جدی باید محدودیت‌های آن را در نظر بگیرید.

۱. فقط JavaScript اجرا می‌شود

کدهای PHP، Python، Go یا Java را نمی‌توان مستقیماً داخل این محیط اجرا کرد. اگر ربات فعلی شما با PHP نوشته شده باشد، باید منطق Handlerهای موردنظر را با JavaScript بازنویسی کنید یا معماری ترکیبی داشته باشید.

۲. امکان استفاده آزاد از پکیج‌های npm وجود ندارد

در Runtime فقط SDK پلتفرم و ماژول‌های خود پروژه در دسترس‌اند. بنابراین نمی‌توان هر کتابخانه npm را مانند یک پروژه معمولی Node.js نصب و در محیط اجرا Import کرد.

۳. فایل‌سیستم در دسترس نیست

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

۴. محدودیت پردازش فایل

در نسخه فعلی می‌توان فایل‌های موجود روی سرورهای تلگرام را با file_id ارسال، فوروارد یا دوباره استفاده کرد؛ اما دریافت بایت خام فایل از طریق getFile و دانلود محتوا یا آپلود مستقیم فایل جدید از داخل Handler پشتیبانی نمی‌شود.

به همین دلیل، ربات‌هایی که روی تصاویر پردازش سنگین انجام می‌دهند، ویدئو تبدیل می‌کنند، فایل ZIP می‌سازند یا از FFmpeg استفاده می‌کنند همچنان به سرور خارجی نیاز خواهند داشت.

۵. محدودیت پاسخ HTTP

پاسخ درخواست‌های خارجی باید متنی باشد و محتوای باینری پشتیبانی نمی‌شود. همچنین حجم کل پاسخ HTTP خارجی سقف مشخصی دارد که در مستندات فعلی ۳۲ مگابایت اعلام شده است.

۶. وابستگی بیشتر به تلگرام

با انتقال منطق و دیتابیس به زیرساخت Telegram Serverless، پروژه بیش از گذشته به ابزارها، محدودیت‌ها و سیاست‌های تلگرام وابسته می‌شود. برای سرویس‌های تجاری حساس بهتر است نسخه پشتیبان اطلاعات و برنامه خروج از پلتفرم در نظر گرفته شود.

چه ربات‌هایی برای Telegram Serverless مناسب‌اند؟

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

• ربات پاسخ‌گویی و سؤالات متداول
• ربات ثبت‌نام و جمع‌آوری اطلاعات
• ربات نظرسنجی و مسابقه
• ربات مدیریت ساده کانال یا گروه
• ربات پیگیری سفارش از طریق API سایت
• ربات دریافت اعلان از سرویس‌های دیگر
• ربات ثبت تیکت پشتیبانی
• بک‌اند سبک برای Telegram Mini App
• بازی‌های متنی و سیستم امتیازدهی
• ربات‌های متصل به API هوش مصنوعی

چه پروژه‌هایی بهتر است همچنان سرور اختصاصی داشته باشند؟

• پردازش و تبدیل ویدئو و صوت
• پردازش مستقیم تصاویر و فایل‌های کاربران
• ربات‌های دارای Queue و Workerهای پیچیده
• پروژه‌هایی با کتابخانه‌های تخصصی متعدد
• سرویس‌های دارای دیتابیس بزرگ و گزارش‌گیری سنگین
• سیستم‌هایی که نیازمند کنترل کامل شبکه و سیستم‌عامل‌اند
• پروژه‌هایی که باید هم‌زمان خارج از تلگرام نیز سرویس بدهند

نکات امنیتی مهم در ساخت ربات بدون سرور

توکن‌ها را داخل کد قرار ندهید

توکن Bot API، توکن CLI و کلید API سرویس‌های خارجی نباید داخل کدی قرار بگیرند که احتمال انتشار عمومی آن وجود دارد.

ورودی کاربران را اعتبارسنجی کنید

متن پیام، Callback Data، کد سفارش و هر داده دریافتی از کاربر باید نامعتبر فرض شود تا زمانی که ساختار آن بررسی شده باشد.

شناسه کاربر را با عدد ۳۲ بیتی ذخیره نکنید

شناسه‌های کاربران و گفتگوهای تلگرام ممکن است بزرگ باشند. نوع داده انتخابی باید توانایی ذخیره ایمن شناسه‌های تلگرام را داشته باشد.

API خارجی را احراز هویت کنید

اگر ربات به API سایت شما متصل است، صرفاً مخفی‌بودن آدرس API امنیت محسوب نمی‌شود. از امضای HMAC، توکن محدودشده، تاریخ انقضا، Nonce و Rate Limit استفاده کنید.

خطاهای فنی را برای کاربر نمایش ندهید

پیام خطا برای کاربر باید عمومی و قابل فهم باشد. جزئیاتی مانند Stack Trace، آدرس داخلی API، نام جدول دیتابیس و کلیدها فقط باید در Log ثبت شوند.

برای درخواست‌های خارجی Timeout در نظر بگیرید

کندشدن API خارجی نباید باعث معطل‌ماندن طولانی Handler شود. درخواست‌ها را کنترل کنید و برای خطا، پاسخ جایگزین مناسبی داشته باشید.

آیا Telegram Serverless برای کسب‌وکارها مناسب است؟

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

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