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

1. [01]

   توکن ربات را از BotFather بگیر. در تلگرام به @BotFather پیام بده، دستور /newbot را بفرست، یک نام و یک آیدی که به bot ختم می‌شود انتخاب کن. در جواب یک توکن می‌گیری؛ همان رشته کلید کنترل ربات توست، پس در کد ننویس و در متغیر محیطی TELEGRAM_BOT_TOKEN نگه دار.

2. [02]

   یک کلید 1xAi بساز. در 1xai.ir ثبت‌نام کن و از داشبورد یک کلید API صادر کن. همان کلید به همهٔ مدل‌های OpenAI، Anthropic، Google و DeepSeek وصل می‌شود و هزینه از اعتبار کیف پول تومانی‌ات کسر می‌شود.

3. [03]

   کتابخانه‌ها را نصب کن. پایتون ۳٫۱۰ یا بالاتر لازم است. برای نسخهٔ ساده pip install requests openai و برای نسخهٔ کامل pip install python-telegram-bot openai کافی است؛ هیچ SDK اختصاصی دیگری لازم نیست.

4. [04]

   base_url را به 1xai.ir/v1 تغییر بده. کلاینت رسمی OpenAI را با base_url برابر https://1xai.ir/v1 و کلید 1xai خودت بساز. بقیهٔ کد دست‌نخورده می‌ماند؛ مدل را فقط با نامش انتخاب می‌کنی و درخواست به سرویس‌دهندهٔ درست مسیر داده می‌شود.

5. [05]

   پیام‌های تلگرام را به مدل وصل کن. هر پیام متنی که از getUpdates یا از هندلر python-telegram-bot می‌رسد را به chat.completions بده و متن پاسخ را با sendMessage برگردان. برای حافظهٔ گفتگو فقط چند پیام آخر هر چت را نگه دار، نه کل تاریخچه را.

6. [06]

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

این کد کامل است و همان‌طور که هست اجرا می‌شود. دو متغیر محیطی می‌خواهد — TELEGRAM_BOT_TOKEN و ONEXAI_API_KEY — و هیچ فریم‌ورک اضافه‌ای لازم ندارد. منطقش ساده است: در یک حلقه از تلگرام آپدیت می‌گیرد، متن هر پیام را به مدل می‌دهد و جواب را برمی‌گرداند.

# bot.py — کوتاه‌ترین ربات هوش مصنوعی تلگرام (long polling)
# pip install requests openai
import os
import requests
from openai import OpenAI

TG_TOKEN = os.environ["TELEGRAM_BOT_TOKEN"]      # از BotFather
TG_API = f"https://api.telegram.org/bot{TG_TOKEN}"

client = OpenAI(
    base_url="https://1xai.ir/v1",               # تنها تفاوت با OpenAI
    api_key=os.environ["ONEXAI_API_KEY"],        # کلید 1xai-... از داشبورد
)

MODEL = "gpt-4o-mini"                            # سریع و کم‌هزینه
SYSTEM = "تو یک دستیار فارسی‌زبان هستی. کوتاه، دقیق و بدون حاشیه جواب بده."


def ask(text: str) -> str:
    resp = client.chat.completions.create(
        model=MODEL,
        messages=[
            {"role": "system", "content": SYSTEM},
            {"role": "user", "content": text},
        ],
        max_tokens=400,                          # سقف خروجی = سقف هزینه
    )
    return resp.choices[0].message.content


def send(chat_id: int, text: str) -> None:
    requests.post(
        f"{TG_API}/sendMessage",
        json={"chat_id": chat_id, "text": text},
        timeout=30,
    )


offset = None
while True:                                      # long polling
    r = requests.get(
        f"{TG_API}/getUpdates",
        params={"offset": offset, "timeout": 50},
        timeout=60,
    )
    for update in r.json().get("result", []):
        offset = update["update_id"] + 1
        message = update.get("message") or {}
        text = message.get("text")
        if not text:
            continue
        chat_id = message["chat"]["id"]
        if text.startswith("/start"):
            send(chat_id, "سلام! سوالت را بنویس تا جواب بدهم.")
            continue
        try:
            send(chat_id, ask(text))
        except Exception as exc:                 # هرگز حلقه را نخوابان
            print("error:", exc)
            send(chat_id, "الان نتوانستم جواب بدهم. چند لحظه بعد دوباره بفرست.")

نکتهٔ ریز اما مهم: مقدار offset باعث می‌شود هر آپدیت فقط یک بار پردازش شود؛ بدون آن ربات پیام‌های قبلی را بارها جواب می‌دهد و بارها هزینه می‌گیرد. همچنین استثناها را داخل حلقه بگیر تا یک خطای موقت شبکه کل ربات را نخواباند.

وقتی ربات بیش از چند کاربر پیدا کند، نسخهٔ همزمان (async) لازم می‌شود تا یک درخواست کند، بقیه را پشت خودش نگه ندارد. کتابخانهٔ python-telegram-bot هندلرها، دستورها و نشانگر «در حال تایپ» را آماده دارد. حافظهٔ گفتگو هم این‌جا با یک deque محدود پیاده شده تا کانتکست، و در نتیجه هزینه، بی‌نهایت رشد نکند.

# bot_ptb.py — نسخهٔ async با حافظهٔ کوتاه گفتگو
# pip install "python-telegram-bot>=21" openai
import os
from collections import defaultdict, deque

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

client = AsyncOpenAI(
    base_url="https://1xai.ir/v1",
    api_key=os.environ["ONEXAI_API_KEY"],
)

MODEL = "gpt-4o-mini"
SYSTEM = "تو دستیار فارسی‌زبان یک ربات تلگرام هستی. کوتاه و دقیق جواب بده."
HISTORY_TURNS = 6                                # فقط ۶ دور آخر نگه داشته می‌شود
history: dict[int, deque] = defaultdict(lambda: deque(maxlen=HISTORY_TURNS * 2))


async def start(update: Update, _: ContextTypes.DEFAULT_TYPE) -> None:
    await update.message.reply_text(
        "سلام! هر سوالی داری بپرس. با /reset حافظهٔ گفتگو پاک می‌شود."
    )


async def reset(update: Update, _: ContextTypes.DEFAULT_TYPE) -> None:
    history[update.effective_chat.id].clear()
    await update.message.reply_text("حافظهٔ گفتگو پاک شد.")


async def chat(update: Update, _: ContextTypes.DEFAULT_TYPE) -> None:
    chat_id = update.effective_chat.id
    turns = history[chat_id]
    turns.append({"role": "user", "content": update.message.text})

    await update.effective_chat.send_action(ChatAction.TYPING)
    resp = await client.chat.completions.create(
        model=MODEL,
        messages=[{"role": "system", "content": SYSTEM}, *turns],
        max_tokens=500,
    )
    answer = resp.choices[0].message.content
    turns.append({"role": "assistant", "content": answer})
    await update.message.reply_text(answer)


app = Application.builder().token(os.environ["TELEGRAM_BOT_TOKEN"]).build()
app.add_handler(CommandHandler("start", start))
app.add_handler(CommandHandler("reset", reset))
app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, chat))
app.run_polling()

برای عوض کردن مدل فقط مقدار MODEL را تغییر بده: نام‌های claude-* به Anthropic، gemini-* به Google و بقیه به OpenAI مسیر داده می‌شوند. فهرست کامل در صفحهٔ مدل‌ها است و مرجع کامل پارامترها در مستندات.

هزینهٔ یک ربات تلگرامی را طول پیام‌ها و انتخاب مدل تعیین می‌کند، نه تعداد کاربرها به‌تنهایی. پنج اهرم زیر به ترتیب اثر آمده‌اند:

1. [01]

   مدل ارزان را پیش‌فرض کن. بیشتر پیام‌های یک ربات تلگرامی کوتاه و روزمره‌اند. مدل‌های سریع مثل gpt-4o-mini یا gemini-2.5-flash چند برابر ارزان‌تر از پرچم‌دارها هستند و برای این حجم کار کافی‌اند؛ مدل سنگین را فقط پشت یک دستور جداگانه مثل /pro بگذار.

2. [02]

   max_tokens بگذار. بدون سقف خروجی، یک سوال باز می‌تواند جوابی چند برابر انتظارت تولید کند. سقفی از ۴۰۰ تا ۶۰۰ توکن برای پاسخ چت کاملاً کافی است و بیشترین اثر را روی قبض دارد.

3. [03]

   تاریخچه را کوتاه نگه دار. هزینهٔ ورودی با کل کانتکست حساب می‌شود، پس فرستادن تمام تاریخچهٔ یک چت در هر پیام یعنی پرداخت دوباره برای همان متن. نگه داشتن چند دور آخر (مثل کد بالا) هزینهٔ ورودی را ثابت نگه می‌دارد.

4. [04]

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

5. [05]

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

• خطای ۴۰۹ Conflict. یعنی همزمان بیش از یک نمونه از ربات دارد پولینگ می‌کند. قبل از اجرای نسخهٔ جدید، نسخهٔ قبلی را حتماً ببند.
• دسترسی به api.telegram.org. این دامنه از داخل ایران پایدار نیست؛ کد ربات معمولاً روی سرور خارج اجرا می‌شود. فراخوانی مدل اما به 1xai.ir می‌رود که از داخل ایران هم بدون وی‌پی‌ان در دسترس است.
• پیام‌های بلندتر از حد تلگرام. سقف هر پیام حدود ۴۰۹۶ کاراکتر است؛ جواب‌های طولانی مدل را قبل از ارسال تکه کن، یا با max_tokens جلوی طولانی شدنشان را بگیر.
• لو رفتن توکن‌ها. نه توکن تلگرام و نه کلید 1xAi را داخل کد یا مخزن گیت نگذار؛ متغیر محیطی استفاده کن. اگر کلیدی لو رفت، از داشبورد باطلش کن و کلید تازه بساز.