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

می‌خواهی یک ربات داشته باشی که در تلگرام به سؤال مشتری‌ها جواب بدهد، متن کپشن پیشنهاد کند یا برای خودت دستیار شخصی باشد. نمونه‌کدش را از ChatGPT گرفته‌ای، ولی دو جا گیر کرده‌ای: کلید OpenAI بدون کارت اعتباری خارجی به دستت نمی‌رسد، و ربات فقط تا وقتی جواب می‌دهد که لپ‌تاپت روشن است. این آموزش ساخت ربات تلگرام هوش مصنوعی را از صفر تا ربات همیشه‌روشن پیش می‌برد و لازم نیست برنامه‌نویس باشی.

مسیر چهار قدم دارد: گرفتن توکن از BotFather، گرفتن کلید API هوش مصنوعی از چابکان با پرداخت ریالی، کپی کردن یک کد آمادهٔ پایتون، و بالا آوردن ربات روی هاست. اگر ربات تلگرامی آماده‌ای داری که فقط باید آنلاین شود و به مدل هوش مصنوعی وصل نیست، راهنمای پروژه ChatGPT یا Claude را آنلاین کنیم کوتاه‌تر است.

 

 

ربات تلگرام هوش مصنوعی چطور کار می‌کند؟

سه طرف در کار است: تلگرام، کد تو و مدل هوش مصنوعی. کاربر به ربات پیام می‌دهد. کد تو پیام را از سرور تلگرام می‌گیرد و آن را به API مدل می‌فرستد. مدل جواب را برمی‌گرداند و کد همان را برای کاربر در تلگرام می‌فرستد.

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

کدی که در این آموزش می‌نویسیم با روش polling کار می‌کند، یعنی ربات خودش مدام از تلگرام پیام تازه می‌گیرد. پس دامنه و SSL لازم ندارد. روش دیگر webhook است که تلگرام پیام‌ها را به یک آدرس HTTPS می‌فرستد. فرق این دو را در Webhook چیست؟ توضیح داده‌ایم. اگر هنوز مطمئن نیستی چت‌بات به کارت می‌آید، چت بات چیست؟ را بخوان.

قبل از شروع این‌ها را آماده کن:

• یک حساب تلگرام
• یک حساب چابکان برای کلید API هوش مصنوعی و هاست ربات
• یک ویرایشگر متن ساده، مثل Notepad یا VS Code، برای ساختن سه فایل

قدم ۱: ساخت ربات در BotFather و گرفتن توکن

BotFather ربات رسمی خود تلگرام برای ساختن ربات‌های دیگر است. مرحله‌ها طبق راهنمای رسمی تلگرام برای BotFather این‌هاست:

1. در تلگرام @BotFather را پیدا کن و Start را بزن.
2. دستور /newbot را بفرست.
3. یک اسم نمایشی بده، مثلاً «دستیار کافه نارنج». این اسم را بعداً هم می‌توانی عوض کنی.
4. یک نام کاربری انگلیسی بده که آخرش bot باشد، مثل narenj_cafe_bot. نام کاربری بعداً قابل تغییر نیست.
5. BotFather یک توکن می‌دهد که شبیه 110201543:AAHdqTcv... است. آن را جایی امن نگه دار.

هر کسی که این توکن را داشته باشد می‌تواند ربات تو را کنترل کند. آن را در گروه، اسکرین‌شات یا مخزن GitHub نگذار. اگر لو رفت، در BotFather توکن تازه بگیر تا توکن قبلی باطل شود.

قدم ۲: گرفتن کلید API هوش مصنوعی بدون کارت خارجی

مغز ربات مدل زبانی است که به پیام‌ها جواب می‌دهد. حساب OpenAI کارت اعتباری خارجی می‌خواهد. هوش مصنوعی ابری چابکان یک API سازگار با OpenAI است: اعتبارش را با پرداخت ریالی از درگاه داخلی شارژ می‌کنی و با یک کلید به مدل‌های OpenAI، Gemini، Claude، DeepSeek، Qwen و چند خانوادهٔ دیگر دسترسی داری.

طبق مستند راه‌اندازی هوش مصنوعی چابکان این‌طور پیش برو:

1. در پنل چابکان از منوی محصولات، «هوش مصنوعی» را باز کن و «ایجاد سرویس هوش مصنوعی» را بزن.
2. یک اسم بده، مثلاً telegram-bot، پلن را انتخاب کن و صبر کن وضعیت سرویس «فعال» شود. فهرست مدل‌هایی که می‌توانی صدا بزنی به پلن سرویس بستگی دارد.
3. در زبانهٔ «اعتبار و شارژ» اعتبار مصرف مدل را از کیف پول شارژ کن. هزینهٔ پلن و اعتبار مصرف جدا هستند. تا اعتبار بیشتر از صفر نباشد، مدل جواب نمی‌دهد.
4. در زبانهٔ «کلیدهای API» روی «ایجاد کلید» بزن و اسمی مثل telegram-bot بده.
5. کلید را همان لحظه کپی کن. کلید کامل فقط یک بار نمایش داده می‌شود و با sk-chbk- شروع می‌شود.

اگر اولین بار است کلید API می‌گیری، آموزش کار با API ChatGPT و ساخت کلید همین مراحل را با جزئیات بیشتر و یک تست curl آورده است.

کدام مدل را برای ربات انتخاب کنم؟

در زبانهٔ «مدل‌های قابل استفاده» فهرست مدل‌ها را می‌بینی. کد ربات به شناسهٔ مدل نیاز دارد، نه اسم نمایشی آن. مستندات چابکان در مثال‌هایش از openai/gpt-4o-mini استفاده می‌کند. این مدل در پلن پایه هم هست و برای ربات پرسش و پاسخ ساده انتخاب مناسبی است. قیمت هر مدل را در صفحهٔ مدل‌های OpenAI در چابکان ببین. اگر بعداً خواستی مدل را عوض کنی، فقط یک متغیر را تغییر می‌دهی و به کد دست نمی‌زنی.

قبل از رفتن سراغ کد، در صفحهٔ سرویس بخش «چت با مدل» را باز کن و با همین مدل یک پیام کوتاه بفرست. این اولین تست بدون کد است: اگر آنجا جواب گرفتی، سرویس و اعتبار درست کار می‌کنند و اگر ربات بعداً جواب نداد، باید سراغ کلید و کد بروی.

قدم ۳: کد ربات تلگرام هوش مصنوعی با پایتون

روی دسکتاپ یک پوشه به اسم ai-bot بساز. سه فایل لازم داری: main.py که کد ربات است، requirements.txt که فهرست کتابخانه‌هاست، و .env.example که فقط اسم متغیرها را برای یادآوری نگه می‌دارد.

فایل main.py:

import logging
import os
from collections import defaultdict, deque

from openai import AsyncOpenAI, OpenAIError
from telegram import Update
from telegram.ext import (
    Application,
    CommandHandler,
    ContextTypes,
    MessageHandler,
    filters,
)

logging.basicConfig(level=logging.INFO)
logging.getLogger("httpx").setLevel(logging.WARNING)
log = logging.getLogger("bot")

BOT_TOKEN = os.environ["BOT_TOKEN"]
MODEL = os.environ.get("CHABOKAN_AI_MODEL", "openai/gpt-4o-mini")
SYSTEM_PROMPT = os.environ.get(
    "SYSTEM_PROMPT",
    "You are a friendly assistant. Answer briefly, in the same language as the user.",
)

client = AsyncOpenAI(
    api_key=os.environ["CHABOKAN_AI_API_KEY"],
    base_url="https://ai.chabokan.net/v1",
    timeout=60,
    max_retries=2,
)

# Short memory: the last 10 messages of each chat, kept in RAM only
history = defaultdict(lambda: deque(maxlen=10))


async def start(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    await update.effective_message.reply_text("Hi! Send me any question.")


async def reset(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    history[update.effective_chat.id].clear()
    await update.effective_message.reply_text("Memory cleared. Let's start over.")


async def chat(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    message = update.effective_message
    chat_id = update.effective_chat.id
    history[chat_id].append({"role": "user", "content": message.text})
    await context.bot.send_chat_action(chat_id, "typing")
    try:
        completion = await client.chat.completions.create(
            model=MODEL,
            messages=[{"role": "system", "content": SYSTEM_PROMPT}, *history[chat_id]],
        )
        answer = completion.choices[0].message.content or "..."
    except OpenAIError as error:
        history[chat_id].pop()
        log.error("AI error: %s", error)
        await message.reply_text("Sorry, I can't answer right now. Try again later.")
        return
    history[chat_id].append({"role": "assistant", "content": answer})
    await message.reply_text(answer[:4096])


def main() -> None:
    app = Application.builder().token(BOT_TOKEN).build()
    app.add_handler(CommandHandler("start", start))
    app.add_handler(CommandHandler("reset", reset))
    text_only = filters.UpdateType.MESSAGE & filters.TEXT & ~filters.COMMAND
    app.add_handler(MessageHandler(text_only, chat))
    log.info("Bot is running...")
    app.run_polling()


if __name__ == "__main__":
    main()

فایل requirements.txt:

python-telegram-bot>=22,<23
openai>=3,<4

فایل .env.example:

BOT_TOKEN=
CHABOKAN_AI_API_KEY=
CHABOKAN_AI_MODEL=openai/gpt-4o-mini
SYSTEM_PROMPT=

کد با کتابخانهٔ python-telegram-bot نوشته شده است. لازم نیست همهٔ کد را بفهمی، ولی چهار جایش را بشناس:

• توکن و کلید داخل کد نیستند. کد آن‌ها را از متغیرهای محیطی BOT_TOKEN و CHABOKAN_AI_API_KEY می‌خواند. خیلی از نمونه‌کدهای اینترنتی کلید را مستقیم در کد می‌نویسند و با اولین آپلود در GitHub لو می‌رود.
• base_url روی چابکان است. کتابخانه همان SDK رسمی OpenAI است و فقط آدرس پایه به https://ai.chabokan.net/v1 اشاره می‌کند. این همان الگویی است که در نمونه‌کدهای زبان‌های برنامه‌نویسی چابکان آمده.
• ربات حافظهٔ کوتاه دارد. ده پیام آخر هر گفتگو در history می‌ماند تا ربات بفهمد «همان قبلی را کوتاه‌تر کن» یعنی چه. دستور /reset این حافظه را پاک می‌کند. با ری‌استارت سرویس هم حافظه خالی می‌شود.
• شخصیت ربات در SYSTEM_PROMPT است. اگر ربات برای کافه یا فروشگاهت است، در پنل یک متغیر SYSTEM_PROMPT بساز و بنویس ربات چه کسی است و به چه سؤال‌هایی جواب بدهد. متن پیام‌های خوشامد و خطا را هم داخل کد می‌توانی به فارسی برگردانی.

تلگرام هر پیام را حداکثر ۴۰۹۶ کاراکتر قبول می‌کند. برای همین جواب‌های بلندتر در کد بریده می‌شوند تا ربات خطا ندهد.

قدم ۴: روشن نگه داشتن ربات به‌صورت ۲۴ ساعته روی هاست

قدم آخر این است که ربات جایی اجرا شود که همیشه روشن است. هاست ربات تلگرام چابکان همین کار را می‌کند: کد را آپلود می‌کنی، کتابخانه‌ها خودکار نصب می‌شوند و ربات بدون روشن ماندن لپ‌تاپ تو جواب می‌دهد.

 

 

ساخت سرویس Python روی دیتاسنتر اروپا

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

بعد از ساخت، در «تنظیمات» سرویس گزینهٔ «ورژن Python» را روی 3.12 بگذار و «ذخیرهٔ تغییرات» را بزن. نسخهٔ فعلی کتابخانه‌های python-telegram-bot و openai به Python 3.10 یا بالاتر نیاز دارند و چابکان تا 3.12 را پشتیبانی می‌کند.

آپلود فایل‌ها با فایل منیجر

1. از داشبورد سرویس، «مدیریت فایل‌ها» را باز کن.
2. فایل‌های نمونهٔ داخل پوشهٔ پیش‌فرض app را پاک کن.
3. روی کامپیوترت وارد پوشهٔ ai-bot شو، سه فایل را انتخاب کن و همان‌ها را zip کن. فایل zip را آپلود کن و Extract بزن. main.py و requirements.txt باید مستقیم داخل app باشند، نه داخل زیرپوشه‌ای مثل app/ai-bot.
4. اگر متغیرهای محیطی قدم بعد را قبلاً ساخته‌ای، سرویس را یک بار ری‌استارت کن تا کتابخانه‌ها نصب شوند و ربات اجرا شود.

جزئیات این روش در مستند استقرار با فایل منیجر آمده و روش‌های CLI، Git و FTP هم کنارش هستند. اسم فایل را عمداً main.py گذاشتیم: طبق مستند اجرای خودکار در Python، چابکان فایل main.py را با هر روشن شدن سرویس خودش اجرا می‌کند و پکیج‌های requirements.txt را هم خودکار نصب می‌کند.

گذاشتن توکن و کلید در متغیرهای محیطی

در «تنظیمات» سرویس به بخش متغیرهای محیطی برو و با «افزودن متغیر» این سه را بساز:

اسم متغیر	مقدار
BOT_TOKEN	توکنی که BotFather داد
CHABOKAN_AI_API_KEY	کلیدی که با sk-chbk- شروع می‌شود
CHABOKAN_AI_MODEL	شناسهٔ مدل، مثلاً openai/gpt-4o-mini
SYSTEM_PROMPT (اختیاری)	شخصیت ربات و اینکه به چه سؤال‌هایی جواب بدهد

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

چک کردن لاگ و اولین پیام

از منوی سرویس، بخش «لاگ‌ها» را باز کن. اگر خط Bot is running... را دیدی، ربات بالا آمده است. حالا در تلگرام ربات خودت را باز کن، /start را بزن و یک سؤال بپرس.

ربات طبق همین تنظیم بعد از هر ری‌استارت دوباره بالا می‌آید. برای برگشت خودکار بعد از کرش، مستند Supervisor را ببین.

خطاهای رایج در ساخت ربات تلگرام هوش مصنوعی

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

چیزی که در لاگ می‌بینی	علت	چه کار کنی
KeyError: 'BOT_TOKEN'	متغیر ساخته نشده یا اسمش فرق دارد	اسم متغیر را در پنل دقیقاً مثل کد بنویس
InvalidToken	توکن ناقص کپی شده یا باطل شده	توکن را دوباره از BotFather کپی کن
Conflict	دو نسخه از ربات هم‌زمان در حال اجراست	نسخهٔ دیگر را روی کامپیوتر یا سرویس دیگر خاموش کن
AI error: Error code: 401	کلید API اشتباه، ناقص یا لغوشده است	کلید را دوباره paste کن یا کلید تازه بساز
AI error: Error code: 402	اعتبار مصرف مدل یا سقف ماهانهٔ کلید تمام شده	از زبانهٔ «اعتبار و شارژ» شارژ کن
AI error: Error code: 404	شناسهٔ مدل غلط است یا مدل در پلن سرویس تو نیست	شناسه را از «مدل‌های قابل استفاده» عیناً کپی کن
AI error: Error code: 429	تعداد درخواست در دقیقه از سقف پلن بیشتر شده	چند ثانیه صبر کن و دوباره پیام بده
Not Found requirements.txt	فایل داخل زیرپوشه افتاده	requirements.txt را در ریشهٔ app بگذار
NetworkError یا TimedOut	سرویس به سرور تلگرام نمی‌رسد، معمولاً چون روی دیتاسنتر ایران ساخته شده	سرویس را روی دیتاسنتر اروپا بساز

فهرست کامل کدهای خطای API در راهنمای عیب‌یابی هوش مصنوعی چابکان آمده است.

کنترل هزینهٔ مصرف ربات

هزینهٔ اصلی ربات مصرف مدل است: هر پیامی که ربات جواب می‌دهد از اعتبار هوش مصنوعی کم می‌کند. چند کار ساده جلوی خرج غیرمنتظره را می‌گیرد:

• سقف ماهانه برای کلید بگذار. موقع ساختن کلید می‌توانی سقف مصرف ماهانه و تاریخ انقضا تعیین کنی. اگر کلید لو برود یا ربات شلوغ شود، مصرف از همان سقف بالاتر نمی‌رود.
• برای ربات کلید جدا بساز. اگر برای ابزار دیگری هم کلید لازم داری، کلید دیگری بساز تا هر کدام را جداگانه لغو کنی.
• مدل سبک انتخاب کن. برای پرسش و پاسخ کوتاه، مدل‌های mini معمولاً کافی‌اند. مدل‌های بزرگ‌تر را برای کارهایی نگه دار که واقعاً لازم دارند.
• حافظه را کوتاه نگه دار. هر پیام قبلی که در history می‌ماند، دوباره به مدل فرستاده می‌شود. عدد maxlen را بی‌دلیل بزرگ نکن.
• مصرف را ببین. پنل سرویس هوش مصنوعی لاگ درخواست‌ها را به تفکیک مدل نشان می‌دهد.

اگر ربات فقط برای خودت یا تیمت است، از ChatGPT بخواه کد را طوری تغییر بدهد که فقط به آیدی‌های عددی مشخصی جواب بدهد. آن آیدی‌ها را هم در یک متغیر محیطی بگذار.

از ربات ساده تا ربات کاربردی

این کد یک پایهٔ کوچک است. بعد از اینکه کار کرد، می‌توانی قدم‌به‌قدم چیزهای دیگری به آن اضافه کنی: جواب دادن بر اساس منوی کافه یا لیست محصولات، ذخیرهٔ گفتگوها در SQLite، یا دکمه‌های شیشه‌ای. برای هر تغییر، کد فعلی را به ChatGPT یا Claude بده و دقیق بگو چه می‌خواهی. این کد پیام‌ها را یکی‌یکی جواب می‌دهد. اگر ربات شلوغ شد و کاربرها منتظر هم ماندند، از ChatGPT بخواه concurrent_updates(True) را به Application.builder() اضافه کند.

اگر خودت می‌خواهی کد را در ترمینال با یک دستیار هوش مصنوعی گسترش بدهی، Claude Code چیست؟ را بخوان. اگر می‌خواهی ربات به یک سایت یا سرویس دیگر وصل شود و پیام‌ها را با webhook بگیرد، اول دامنه و SSL را روی سرویس راه بینداز. مسیرش در راهنمای آنلاین کردن پروژه ChatGPT آمده است.

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

برای ساخت ربات تلگرام هوش مصنوعی دو چیز لازم داشتی: کلید مدل و جای اجرای ربات. هر دو در یک پنل چابکان است. هاست ربات پرداخت ساعتی دارد، پس می‌توانی سرویس را چند روز با چند کاربر آزمایشی امتحان کنی و اگر لازمش نداشتی، حذفش کنی.

برای شروع، یک سرویس روی هاست ربات تلگرام چابکان بساز و کلید مدل را از هوش مصنوعی ابری چابکان بگیر. با اعتبار هدیهٔ ۱۰۰ هزار تومانی می‌توانی مصرف هوش مصنوعی ربات را تست کنی. این اعتبار هزینهٔ هاست ربات را پوشش نمی‌دهد.

سوالات متداول درباره ساخت ربات تلگرام هوش مصنوعی

برای ساخت ربات تلگرام هوش مصنوعی باید برنامه‌نویسی بلد باشم؟

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

بدون کارت اعتباری خارجی می‌شود به ChatGPT وصل شد؟

بله. API هوش مصنوعی چابکان با OpenAI سازگار است و اعتبارش با پرداخت ریالی از درگاه داخلی شارژ می‌شود. در کد فقط base_url روی https://ai.chabokan.net/v1 می‌رود و بقیهٔ کد مثل کار با خود OpenAI است.

ربات را روی دیتاسنتر ایران بسازم یا اروپا؟

اروپا. سرورهای داخل ایران به api.telegram.org وصل نمی‌شوند و تانل هم در کانتینرهای چابکان مجاز نیست. اگر ربات را برای پیام‌رسان بله می‌سازی، هاست ربات بله را ببین.

چرا ربات من جواب نمی‌دهد؟

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

به جای ChatGPT می‌توانم از Claude یا DeepSeek استفاده کنم؟

بله. شناسهٔ مدل دیگری را از زبانهٔ «مدل‌های قابل استفاده» کپی کن و در متغیر CHABOKAN_AI_MODEL بگذار. لازم نیست کد را عوض کنی، چون همهٔ مدل‌ها از همان آدرس و همان کلید صدا زده می‌شوند. قبل از تحویل ربات به کاربر، مدل جدید را با چند پیام تست کن.

ربات حرف‌های قبلی کاربر را یادش می‌ماند؟

ده پیام آخر هر گفتگو را تا وقتی سرویس روشن است یادش می‌ماند. با /reset یا ری‌استارت سرویس این حافظه پاک می‌شود. اگر حافظهٔ دائمی می‌خواهی، گفتگوها باید در دیتابیس، مثلاً SQLite، ذخیره شوند.