۱۰۰ هزار تومان هدیهٔ ثبت‌نام، تا ۱ میلیونبا ثبت‌نام گردونهٔ هدیه را بچرخان: دست‌کم ۱۰۰٬۰۰۰ تومان و تا ۱٬۰۰۰٬۰۰۰ تومان اعتبار هدیه، بدون کارت بانکیگردونهٔ هدیه۱ میلیون برای تو، ۱ میلیون برای دوستتدوستانت را دعوت کن: برای هر دوستی که فعال شود ۱٬۰۰۰٬۰۰۰ تومان اعتبار هدیه می‌گیری و خودش هم ۱٬۰۰۰٬۰۰۰ تومانجوایز
1xAi
مقاله

چت تلگرام: ساخت ربات پشتیبانی مشتری با پایتون و مدل 1xAi

یک ربات تلگرام با حدود ۲۰ تا ۳۰ خط پایتون، یک مدل ارزان از طریق API سازگار با OpenAI و یک گروه اپراتور می‌تواند سوال‌های تکراری مشتری را شبانه‌روز جواب بدهد و…

  • منتشر: ۱۶ آبان ۱۴۰۵
  • بروزرسانی: ۱ آذر ۱۴۰۵
  • ۱۰ دقیقه مطالعه
  • چت
  • تلگرام

تیمِ فنیِ 1xAi گیت‌وی را می‌سازد و می‌گرداند — همان‌هایی که هر روز با APIهای OpenAI‏، Anthropic‏، Google و DeepSeek از داخلِ ایران کار می‌کنند. آنچه اینجا می‌خوانی از همان کارِ روزمره درآمده، نه از بازنویسیِ مستنداتِ انگلیسی.

چت تلگرام: ساخت ربات پشتیبانی مشتری با پایتون و مدل 1xAi

در این مقاله (۲۴)

یک ربات تلگرام با حدود ۲۰ تا ۳۰ خط پایتون، یک مدل ارزان از طریق API سازگار با OpenAI و یک گروه اپراتور می‌تواند سوال‌های تکراری مشتری را شبانه‌روز جواب بدهد و بقیه را به آدم بسپارد. این ربات فقط درباره چیزهایی پاسخ قابل اعتماد می‌دهد که اطلاعاتش را در پرامپت یا متن راهنما به آن داده‌اید. هزینه ماهانه هم به تعداد توکن‌های ورودی و خروجی بستگی دارد، پس عدد نهایی را با قیمت زنده مدل انتخابی خودتان حساب کنید. ما در 1xAi درگاه API مورد استفاده در این راهنما را اداره می‌کنیم؛ در ادامه مراحل را از BotFather تا تحویل گفتگو به اپراتور، همراه با کد، می‌بینید.

۱. ربات پشتیبانی مشتری در تلگرام دقیقاً چه کاری می‌کند؟

ربات پشتیبانی، حسابی ویژه در تلگرام است که سوالات تکراری مشتری را جواب می‌دهد و بقیه را به اپراتور انسانی می‌سپارد.

طبق مستندات Telegram APIs در بخش Bot API، چنین حسابی شماره تلفن نمی‌خواهد و رابطش کدی است که روی سرور شما اجرا می‌شود. مشتری در همان چت معمولی تلگرام پیام می‌دهد و برنامه‌ی شما جواب می‌دهد. در این مقاله فقط همین کانال مهم است: فرمان‌هایی مثل /start و /order و لحظه‌ی تحویل به آدم.

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

در الگوی تحویل، ربات خلاصه‌ی گفتگو را برای اپراتور می‌فرستد و به مشتری می‌گوید منتظر چه کسی باشد. اگر پاسخ‌ها را مدل زبانی بنویسد، چت‌بات فارسی ۲۰۲۶ با API OpenAI و Claude راه اتصال مدل را توضیح می‌دهد.

پیام‌ها به دو روش به کد شما می‌رسند، طبق Telegram Bot API به فارسی. در long polling برنامه‌ی شما خودش مدام از تلگرام پیام‌های جدید را می‌پرسد و برای شروع ساده‌تر است. در وب‌هوک تلگرام هر پیام را به یک آدرس HTTPS روی سرور شما می‌فرستد.

۲. چطور با BotFather ربات بسازم و به مدل 1xAi وصل کنم؟

با /newbot در BotFather توکن می‌گیرید، توکن را در متغیر محیطی نگه می‌دارید و با کلاینت OpenAI روی https://1xai.ir/v1 پیام کاربر را به مدل می‌فرستید. مراحل ساخت ربات در آموزش BotFather در telegram-bot-api.info هم به همین ترتیب آمده است.

مراحل ساخت ربات

  1. در تلگرام به @BotFather پیام بدهید و /newbot را بفرستید. اول نام نمایشی و بعد نام کاربری را می‌پرسد، که باید به bot ختم شود.
  2. BotFather یک توکن می‌دهد. با آن هر کسی می‌تواند ربات را کنترل کند، پس آن را مثل رمز عبور نگه دارید و در مخزن کد نگذارید.
  3. توکن و کلید 1xAi را در متغیر محیطی بگذارید:
    export TELEGRAM_TOKEN="توکن-BotFather"
    export ONEXAI_API_KEY="کلید-1xAi"
    
  4. با getMe مطمئن شوید توکن معتبر است. اگر JSON شامل نام کاربری ربات برگشت، آماده‌اید:
    curl "https://api.telegram.org/bot$TELEGRAM_TOKEN/getMe"
    

تست اندپوینت پیش از نوشتن ربات

اگر این درخواست جواب بدهد، کلید و آدرس درست هستند. نام مدل را از فهرست مدل‌ها بردارید.

curl https://1xai.ir/v1/chat/completions \
  -H "Authorization: Bearer $ONEXAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-chat","messages":[{"role":"user","content":"سلام"}]}'

کد کامل ربات

برای اجرا به Python 3.9 یا بالاتر نیاز دارید. نصب: pip install "pyTelegramBotAPI>=4.14" "openai>=1.0"

import os
import telebot
from openai import OpenAI

TELEGRAM_TOKEN = os.environ["TELEGRAM_TOKEN"]
ONEXAI_API_KEY = os.environ["ONEXAI_API_KEY"]

bot = telebot.TeleBot(TELEGRAM_TOKEN)
client = OpenAI(api_key=ONEXAI_API_KEY, base_url="https://1xai.ir/v1")

# اطلاعات نمونه؛ با اطلاعات کسب‌وکار خودتان جایگزین کنید
SYSTEM_PROMPT = (
    "تو دستیار پشتیبانی یک فروشگاه هستی. کوتاه و فارسی جواب بده. "
    "ساعت کاری: شنبه تا چهارشنبه، ۹ تا ۱۷. "
    "اگر جواب را نمی‌دانی، بگو که باید با پشتیبانی انسانی تماس بگیرند."
)

@bot.message_handler(content_types=["text"])
def reply(message):
    try:
        resp = client.chat.completions.create(
            model="deepseek-chat",
            messages=[
                {"role": "system", "content": SYSTEM_PROMPT},
                {"role": "user", "content": message.text},
            ],
            max_tokens=300,
        )
        answer = resp.choices[0].message.content
    except Exception as exc:
        print("API error:", exc)
        answer = "الان نتوانستم جواب بدهم؛ کمی بعد دوباره تلاش کنید."
    bot.reply_to(message, answer)

bot.infinity_polling()

خروجی مورد انتظار (نمونه؛ عبارت دقیق مدل هر بار کمی فرق می‌کند):

  • کاربر: ساعت کاری شما چیست؟
  • ربات: ساعت کاری ما شنبه تا چهارشنبه، از ۹ صبح تا ۵ بعدازظهر است.

مدل ساعت کاری شما را از پیام سیستمی می‌داند، نه از خودش. برای مدل‌های دیگر و کلیدهای بیشتر، راهنمای API چت هوش مصنوعی از ایران را ببینید. برای ساخت یک گام‌به‌گام با LangChain، آموزش LangChain پایتون ۲۰۲۶ را هم بخوانید.

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

برای تماس با 1xAi کیف پول تومانی را با زرین‌پال شارژ می‌کنید. کارت خارجی و VPN لازم نیست.

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

۳. فرمان‌ها و پاسخ سوالات تکراری را چطور تنظیم کنم؟

چهار فرمان /start، /help، /hours و /human را ثبت کنید و پاسخ‌های پرتکرار را در system prompt بگذارید، با این قاعده که ربات بیرون از متن جواب نسازد.

فرمان‌ها

  • /start: پیام خوشامد و معرفی کوتاه.
  • /help: فهرست موضوعاتی که ربات جواب می‌دهد.
  • /hours: ساعات کاری.
  • /human: درخواست اپراتور.

فرمان‌ها را می‌توانید در BotFather با دستور /setcommands ثبت کنید یا با متد setMyCommands از کد:

curl -X POST "https://api.telegram.org/bot<TOKEN>/setMyCommands" \
  -H "Content-Type: application/json" \
  -d '{"commands":[
    {"command":"start","description":"شروع گفتگو"},
    {"command":"help","description":"موضوعات قابل پاسخ"},
    {"command":"hours","description":"ساعات کاری"},
    {"command":"human","description":"صحبت با اپراتور"}]}'

دانش ربات

پرسش‌وپاسخ‌های پرتکرار را مستقیم در system prompt یا یک فایل متنی کوتاه بگذارید و آن را به prompt اضافه کنید. نمونه (کسب‌وکار فرضی است):

تو دستیار پشتیبانی «فروشگاه نمونه» در تلگرام هستی.
فقط فارسی، کوتاه و مؤدبانه جواب بده.
فقط از «دانش» زیر استفاده کن.
اگر پاسخ در دانش نبود، بگو «نمی‌دانم» و بنویس با /human اپراتور را صدا بزنند.
هرگز قیمت، قول یا سیاست جدید نساز.
دانش: ساعات کاری شنبه تا چهارشنبه ۹ تا ۱۷ است.
دانش: مرجوعی تا ۷ روز با فاکتور پذیرفته می‌شود.

برای نوشتن دستورهای دقیق‌تر، راهنمای پرامپت فارسی کمک می‌کند. بعد از ثبت، یک سوال خارج از دانش بفرستید، مثلاً «ارسال به خارج از کشور دارید؟». پاسخ درست «نمی‌دانم» به‌همراه پیشنهاد /human است. اگر ربات جواب ساخت، قاعده را صریح‌تر کنید.

حجم دانش و حافظه

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

برای حافظه، چند پیام آخر هر chat_id را نگه دارید و با هر درخواست بفرستید. چون همه‌ی این پیام‌ها هر بار توکن ورودی حساب می‌شوند، حتماً سقفی برای تعدادشان بگذارید.

۴. چه زمانی ربات باید چت را به اپراتور انسانی بدهد؟

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

در این سه حالت ادامه‌ی گفتگو با مدل بیشتر به ضرر اعتماد کاربر تمام می‌شود تا به نفع سرعت. الگوی فنی هم ساده است و فقط به چند متد Bot API تلگرام نیاز دارد.

الگوی تحویل

  1. یک گروه خصوصی برای اپراتورها بسازید و ربات را عضو کنید. شناسه‌ی گروه می‌شود مقصد همه‌ی تحویل‌ها.
  2. با forwardMessage پیام کاربر را به گروه بفرستید. با sendMessage هم خلاصه‌ی مکالمه را همراه دکمه‌ی «پاسخ» ارسال کنید. اگر نمی‌خواهید برچسب «فوروارد» دیده شود، copyMessage همین کار را بدون آن برچسب انجام می‌دهد.
  3. برای هر chat_id وضعیت bot یا human نگه دارید. تا وقتی وضعیت human است، ربات فقط پیام‌ها را به گروه منتقل می‌کند و خودش جواب نمی‌دهد.
  4. اپراتور دکمه‌ی «پاسخ» را می‌زند، پیام بعدی‌اش با copyMessage به همان chat_id می‌رسد و با /done وضعیت به bot برمی‌گردد.

ساعت‌های بدون اپراتور

خارج از ساعت کاری فقط یک پیام ثابت بفرستید: «درخواست شما ثبت شد و صبح پاسخ می‌دهیم». درخواست را هم در صف بگذارید و زمان دقیق تحویل را وعده ندهید. ساختار صف و ذخیره‌ی مکالمه را در راهنمای چت با مشتری با API: ساخت پشتیبانی هوشمند بیشتر باز کرده‌ایم.

کد تشخیص و تحویل

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

import requests
from datetime import datetime
from zoneinfo import ZoneInfo

TOKEN = "BOT_TOKEN"          # توکن BotFather
OPS_GROUP = -1001234567890   # شناسه‌ی گروه خصوصی اپراتورها
API = f"https://api.telegram.org/bot{TOKEN}"

state, fails, pending, queue = {}, {}, {}, []
KEYWORDS = ("اپراتور", "انسان", "شکایت", "بازگشت وجه", "پول", "پرداخت")

def call(method, **params):
    return requests.post(f"{API}/{method}", json=params, timeout=15).json()

def wants_human(text):
    return text.startswith("/human") or any(k in text for k in KEYWORDS)

def is_open():  # ساعت کاری نمونه
    return 9 <= datetime.now(ZoneInfo("Asia/Tehran")).hour < 18

def hand_off(chat_id, message_id, summary):
    state[chat_id] = "human"
    call("forwardMessage", chat_id=OPS_GROUP, from_chat_id=chat_id, message_id=message_id)
    call("sendMessage", chat_id=OPS_GROUP, text=summary,
         reply_markup={"inline_keyboard": [[{"text": "پاسخ", "callback_data": f"reply:{chat_id}"}]]})
    if not is_open():
        queue.append(chat_id)
        call("sendMessage", chat_id=chat_id,
             text="درخواست شما ثبت شد و صبح پاسخ می‌دهیم.")

def on_user_message(msg):
    chat_id, text = msg["chat"]["id"], msg.get("text", "")
    if state.get(chat_id) == "human":      # ربات ساکت می‌ماند
        call("copyMessage", chat_id=OPS_GROUP, from_chat_id=chat_id,
             message_id=msg["message_id"])
    elif wants_human(text) or fails.get(chat_id, 0) >= 2:
        hand_off(chat_id, msg["message_id"], f"درخواست اپراتور از {chat_id}")
    # در غیر این صورت، همان فراخوانی مدل قبلی

def on_callback(cb):
    if cb["data"].startswith("reply:"):
        pending[cb["from"]["id"]] = int(cb["data"].split(":")[1])
        call("answerCallbackQuery", callback_query_id=cb["id"],
             text="پیام بعدی شما برای کاربر ارسال می‌شود")

def on_operator_message(msg):
    target = pending.get(msg["from"]["id"])
    if not target:
        return
    if msg.get("text") == "/done":
        state[target] = "bot"
        pending.pop(msg["from"]["id"])
    else:
        call("copyMessage", chat_id=target, from_chat_id=msg["chat"]["id"],
             message_id=msg["message_id"])

شمارنده‌ی fails را هر بار که پاسخ مدل «نمی‌دانم» بود یا کاربر روی «مفید نبود» زد یکی زیاد کنید، و با هر پاسخ مفید صفرش کنید. فهرست KEYWORDS را هم با پیام‌های واقعی کاربران خودتان تنظیم کنید، چون واژه‌ی «پرداخت» ممکن است در سؤال‌های ساده هم بیاید.

۵. چطور ربات را ۲۴ ساعته روشن نگه دارم؟

ربات را روی یک فرآیند همیشه‌روشن اجرا کنید؛ systemd یا Docker با restart: always بعد از کرش یا ریبوت سرور آن را دوباره بالا می‌آورد. این کار فقط خود فرآیند را زنده نگه می‌دارد و درباره آپ‌تایم سرور یا شبکه تضمینی نمی‌دهد.

اجرای همیشه‌روشن

نمونه‌ی زیر یک docker-compose.yml حداقلی است. فایل .env کنار آن قرار می‌گیرد و وارد مخزن کد نمی‌شود.

# نمونه
services:
  bot:
    build: .
    container_name: tg-bot
    restart: always
    env_file: .env
    environment:
      - TZ=Asia/Tehran

خطای موقت API

اگر 1xAi یا شبکه برای لحظه‌ای خطا بدهد، ربات نباید ساکت بماند. سه بار با مکث افزایشی تلاش کنید و اگر نشد، یک پیام جایگزین بفرستید.

import os
import time
from openai import OpenAI, APIConnectionError, RateLimitError, InternalServerError

client = OpenAI(base_url="https://1xai.ir/v1", api_key=os.environ["XAI_API_KEY"])
FALLBACK = "الان پاسخ‌دهی کند است؛ چند لحظه دیگر دوباره بپرسید."

def ask(text, tries=3):
    for i in range(tries):
        try:
            r = client.chat.completions.create(
                model="deepseek-chat",
                messages=[{"role": "user", "content": text}],
                timeout=30,
            )
            return r.choices[0].message.content
        except (APIConnectionError, RateLimitError, InternalServerError):
            time.sleep(2 ** i)  # مکث ۱، ۲ و ۴ ثانیه
    return FALLBACK

در هندلر پیام، کافی است جواب را با bot.reply_to(message, ask(message.text)) بفرستید. اگر ربات async است، time.sleep را با asyncio.sleep عوض کنید.

نگهداری توکن‌ها

توکن بات را در مخزن کد نگذارید و آن را فقط از متغیر محیطی بخوانید. اگر توکن لو رفت، طبق راهنمای توکن ربات تلگرام در telegram-bot-api.info آن را از BotFather باطل کنید و توکن تازه بگیرید.

کلید 1xAi را هم در متغیر جداگانه (XAI_API_KEY) نگه دارید. با این کار ابطال یکی از دو کلید، دیگری را از کار نمی‌اندازد.

برای ساختار یک چت ربات تلگرام کامل (long polling، حافظه‌ی SQLite و Dockerfile) می‌توانید مخزن متن‌باز telegram-ai-chat-bot با مجوز MIT را به‌عنوان مرجع ببینید؛ درباره کیفیت آن ادعایی نداریم.

پژوهش و نگارش: code-nest.dev

سوالات متداول

چت بات تلگرام چیست؟

چت‌بات تلگرام حسابی ویژه است که شماره تلفن نمی‌خواهد و رابط آن کدی است که روی سرور شما اجرا می‌شود. با BotFather ساخته می‌شود، پیام کاربر را می‌گیرد، آن را به مدل هوش مصنوعی می‌دهد و پاسخ را برمی‌گرداند. مرجع فنی آن بخش Bot API در مستندات Telegram APIs است.

ربات پشتیبانی چه سوال‌هایی را نباید خودش جواب بدهد؟

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

هزینه ماهانه ربات با deepseek-chat تقریباً چقدر می‌شود؟

در ۶ نوامبر ۲۰۲۶، deepseek-chat در 1xAi برای هر یک میلیون توکن ورودی ۹۸٬۰۲۸ تومان و برای خروجی ۳۹۲٬۱۱۲ تومان بود (نرخ ۲۷۲٬۳۰۰ تومان به ازای هر دلار). در مثالی فرضی، ۱۰۰۰ گفتگو با ۱۰۰۰ توکن ورودی و ۳۰۰ توکن خروجی حدود ۲۱۲,۶۵۲ تومان می‌شود. قیمت زنده را در صفحه مدل‌ها ببینید.

برای دریافت پیام‌ها long polling بهتر است یا وب‌هوک؟

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

آیا برای پشتیبانی مشتری مدل گران‌تری مثل gpt-5 لازم است؟

برای سوال‌های تکراری معمولاً مدل ارزان کافی است، اما این را باید با گفتگوهای واقعی خودتان بسنجید. هزینه خروجی gpt-5 در 1xAi ۳٬۲۶۷٬۶۰۰ تومان به ازای هر میلیون توکن است، یعنی حدود ۸ برابر deepseek-chat. مدل گران‌تر را فقط برای پرسش‌هایی در نظر بگیرید که مدل ارزان در آزمون شما درست جواب نداده است.

مدل‌هایی که در این مقاله دیدی را از داخل ایران امتحان کن.

بدون VPN، صورت‌حساب تومانی، کارمزدِ ۱۵ تا ۳۰٪ بسته به مدل روی نرخِ هر سرویس‌دهنده.